GitLab MCP Server

A comprehensive Model Context Protocol (MCP) server that provides seamless GitLab API integration for Claude Desktop and other MCP clients. Manage your entire GitLab workflow through natural language commands - from project creation to repository operations, CI/CD management, and team collaboration.

🚀 Quick Start

# Install with uvx (recommended)
uvx --from gitlab-clone-mcp-server gitlab-mcp

# Or install as a tool
uv tool install gitlab-clone-mcp-server

🔌 Transport Options

GitLab MCP Server supports three transport types:

# Run with stdio transport (default)
gitlab-mcp stdio

# Run with SSE transport
gitlab-mcp sse --host localhost --port 8000

# Run with Streamable HTTP transport (recommended for production)
gitlab-mcp streamable-http --host localhost --port 8000

See TRANSPORT_OPTIONS.md for detailed configuration.

✨ Key Features

Complete GitLab Integration: 46+ tools covering all major GitLab operations
Natural Language Interface: Control GitLab through conversational commands
Zero Configuration: Works out-of-the-box with your GitLab Personal Access Token
Comprehensive Coverage: Projects, repositories, issues, merge requests, CI/CD, and more
Local Repository Cloning: Clone repositories directly to your local machine
Batch Operations: Perform bulk operations across multiple projects

🛠️ Available Tools (46 Total)

📁 Project Management (12 tools)

Tool	Description
`create_project`	Create new GitLab projects with custom settings
`delete_project`	Permanently delete GitLab projects
`update_project`	Modify project name, description, visibility
`fork_project`	Fork projects to different namespaces
`archive_project`	Archive projects for long-term storage
`unarchive_project`	Restore archived projects
`list_projects`	List all accessible projects with filters
`search_projects`	Search projects by name or keywords
`get_project_milestones`	View project milestones and deadlines
`get_project_labels`	List all project labels and colors
`list_project_hooks`	View configured webhooks
`get_current_user`	Get current user information and permissions

📝 Issue Management (4 tools)

Tool	Description
`get_project_issues`	List issues with state filtering
`create_issue`	Create new issues with descriptions
`update_issue`	Modify issue title, description, state
`close_issue`	Close specific issues

🔀 Merge Request Management (2 tools)

Tool	Description
`get_merge_requests`	List merge requests by state
`create_merge_request`	Create new merge requests
`merge_merge_request`	Merge approved merge requests

📄 File Operations (5 tools)

Tool	Description
`create_file`	Create new files with content
`update_file`	Modify existing file content
`delete_file`	Remove files from repository
`get_file_content`	Read file contents
`get_repository_files`	Browse directory structures

🌿 Repository & Git Operations (15 tools)

Tool	Description
`get_project_branches`	List all repository branches
`create_branch`	Create new branches from any reference
`delete_branch`	Remove branches safely
`get_commits`	View commit history
`create_commit`	Create commits with multiple file changes
`compare_branches`	Compare differences between branches
`revert_commit`	Revert specific commits
`cherry_pick_commit`	Cherry-pick commits between branches
`get_repository_tags`	List all repository tags
`create_tag`	Create release tags
`delete_tag`	Remove tags
`clone_repository`	Clone single repository locally
`clone_group_repositories`	Batch clone all group repositories

🚀 CI/CD Operations (3 tools)

Tool	Description
`get_pipelines`	Monitor pipeline status
`get_pipeline_jobs`	View individual job details
`trigger_pipeline`	Start new pipeline runs

👥 Groups & Collaboration (3 tools)

Tool	Description
`list_groups`	List accessible GitLab groups
`get_group_members`	View group membership
`get_current_user`	Get user profile information

Installation

Using uvx (Recommended)

uvx --from gitlab-clone-mcp-server gitlab-mcp

Using uv

uv tool install gitlab-mcp-server

From source

git clone <repository-url>
cd gitlab-mcp
uv sync

Setup

Get GitLab Personal Access Token:
- Go to GitLab → Settings → Access Tokens
- Create token with api scope
- Copy the token

Set environment variables:

export GITLAB_TOKEN="your_token_here"
export GITLAB_URL="https://gitlab.com"  # optional

Test the server:
```
gitlab-mcp
```

Configuration

Claude Desktop Configuration

Add to your Claude Desktop config (%APPDATA%\Claude\claude_desktop_config.json):

Using stdio transport (recommended)

{
  "mcpServers": {
    "gitlab": {
      "command": "uvx",
      "args": [
        "--from", "gitlab-clone-mcp-server",
        "gitlab-mcp", "stdio"
      ],
      "env": {
        "GITLAB_URL": "https://gitlab.com",
        "GITLAB_TOKEN": "your_gitlab_token_here"
      }
    }
  }
}

Using HTTP transport

If you're running the server with Streamable HTTP transport:

{
  "mcpServers": {
    "gitlab": {
      "url": "http://localhost:8000/mcp",
      "headers": {
        "GITLAB_TOKEN": "your_gitlab_token_here"
      }
    }
  }
}

Headers Integration

For applications using MCPToolset, connect with headers:

import os
from mcp_toolset import MCPToolset, SseServerParams

gitlab_tools = MCPToolset(
    connection_params=SseServerParams(
        url="http://localhost:8000/sse",
        headers={"GITLAB_TOKEN": os.getenv("GITLAB_TOKEN")},
    )
)

💬 Usage Examples

Control GitLab through natural language commands:

Project Management:

"Create a new private project called 'microservice-api'"
"Fork the kubernetes/dashboard project to my namespace"
"Archive the old legacy-system project"

Issue & Code Review:

"Show all open issues in the backend-service project"
"Create merge request from feature/auth-system to main branch"
"Merge the approved MR #23 in mobile-app project"

Repository Operations:

"Create a new config.yaml file with database configuration"
"Show all branches in the web-application project"
"Clone the microservices-platform project to ./local-dev"

CI/CD & Teams:

"Show running pipelines for the deployment project"
"List all my GitLab groups and their members"

🔧 Authentication Setup

GitLab Personal Access Token

Go to GitLab → Settings → Access Tokens
Create token with these scopes:
- ✅ api - Full API access
- ✅ read_repository - Read repository data
- ✅ write_repository - Write repository data
- ✅ read_user - Read user information
Copy the generated token

Environment Variables

Variable	Description	Default
`GITLAB_TOKEN`	Personal Access Token	Required
`GITLAB_URL`	GitLab instance URL	`https://gitlab.com`

🔒 Security Best Practices

Never commit tokens to version control
Use environment variables for token storage
Set token expiration dates when possible
Rotate tokens regularly for enhanced security
Use minimal required scopes for your use case

🐛 Troubleshooting

Token Issues:

❌ GITLAB_TOKEN not set → Set environment variable or provide in headers
❌ 401 Unauthorized → Check token permissions and validity
❌ 403 Forbidden → Verify project access permissions

Git Operations:

❌ Git command not found → Install Git and add to PATH

Test Connection:

curl -H "PRIVATE-TOKEN: your_token" "https://gitlab.com/api/v4/user"

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Made with ❤️ for the GitLab and MCP community

GitLab MCP Server

🚀 Quick Start

# Install with uvx (recommended)
uvx --from gitlab-clone-mcp-server gitlab-mcp

# Or install as a tool
uv tool install gitlab-clone-mcp-server

🔌 Transport Options

GitLab MCP Server supports three transport types:

# Run with stdio transport (default)
gitlab-mcp stdio

# Run with SSE transport
gitlab-mcp sse --host localhost --port 8000

# Run with Streamable HTTP transport (recommended for production)
gitlab-mcp streamable-http --host localhost --port 8000

See TRANSPORT_OPTIONS.md for detailed configuration.

✨ Key Features

Complete GitLab Integration: 46+ tools covering all major GitLab operations
Natural Language Interface: Control GitLab through conversational commands
Zero Configuration: Works out-of-the-box with your GitLab Personal Access Token
Comprehensive Coverage: Projects, repositories, issues, merge requests, CI/CD, and more
Local Repository Cloning: Clone repositories directly to your local machine
Batch Operations: Perform bulk operations across multiple projects

🛠️ Available Tools (46 Total)

📁 Project Management (12 tools)

Tool	Description
`create_project`	Create new GitLab projects with custom settings
`delete_project`	Permanently delete GitLab projects
`update_project`	Modify project name, description, visibility
`fork_project`	Fork projects to different namespaces
`archive_project`	Archive projects for long-term storage
`unarchive_project`	Restore archived projects
`list_projects`	List all accessible projects with filters
`search_projects`	Search projects by name or keywords
`get_project_milestones`	View project milestones and deadlines
`get_project_labels`	List all project labels and colors
`list_project_hooks`	View configured webhooks
`get_current_user`	Get current user information and permissions

📝 Issue Management (4 tools)

Tool	Description
`get_project_issues`	List issues with state filtering
`create_issue`	Create new issues with descriptions
`update_issue`	Modify issue title, description, state
`close_issue`	Close specific issues

🔀 Merge Request Management (2 tools)

Tool	Description
`get_merge_requests`	List merge requests by state
`create_merge_request`	Create new merge requests
`merge_merge_request`	Merge approved merge requests

📄 File Operations (5 tools)

Tool	Description
`create_file`	Create new files with content
`update_file`	Modify existing file content
`delete_file`	Remove files from repository
`get_file_content`	Read file contents
`get_repository_files`	Browse directory structures

🌿 Repository & Git Operations (15 tools)

Tool	Description
`get_project_branches`	List all repository branches
`create_branch`	Create new branches from any reference
`delete_branch`	Remove branches safely
`get_commits`	View commit history
`create_commit`	Create commits with multiple file changes
`compare_branches`	Compare differences between branches
`revert_commit`	Revert specific commits
`cherry_pick_commit`	Cherry-pick commits between branches
`get_repository_tags`	List all repository tags
`create_tag`	Create release tags
`delete_tag`	Remove tags
`clone_repository`	Clone single repository locally
`clone_group_repositories`	Batch clone all group repositories

🚀 CI/CD Operations (3 tools)

Tool	Description
`get_pipelines`	Monitor pipeline status
`get_pipeline_jobs`	View individual job details
`trigger_pipeline`	Start new pipeline runs

👥 Groups & Collaboration (3 tools)

Tool	Description
`list_groups`	List accessible GitLab groups
`get_group_members`	View group membership
`get_current_user`	Get user profile information

Installation

Using uvx (Recommended)

uvx --from gitlab-clone-mcp-server gitlab-mcp

Using uv

uv tool install gitlab-mcp-server

From source

git clone <repository-url>
cd gitlab-mcp
uv sync

Setup

Get GitLab Personal Access Token:
- Go to GitLab → Settings → Access Tokens
- Create token with api scope
- Copy the token

Set environment variables:

export GITLAB_TOKEN="your_token_here"
export GITLAB_URL="https://gitlab.com"  # optional

Test the server:
```
gitlab-mcp
```

Configuration

Claude Desktop Configuration

Add to your Claude Desktop config (%APPDATA%\Claude\claude_desktop_config.json):

Using stdio transport (recommended)

{
  "mcpServers": {
    "gitlab": {
      "command": "uvx",
      "args": [
        "--from", "gitlab-clone-mcp-server",
        "gitlab-mcp", "stdio"
      ],
      "env": {
        "GITLAB_URL": "https://gitlab.com",
        "GITLAB_TOKEN": "your_gitlab_token_here"
      }
    }
  }
}

Using HTTP transport

If you're running the server with Streamable HTTP transport:

{
  "mcpServers": {
    "gitlab": {
      "url": "http://localhost:8000/mcp",
      "headers": {
        "GITLAB_TOKEN": "your_gitlab_token_here"
      }
    }
  }
}

Headers Integration

For applications using MCPToolset, connect with headers:

import os
from mcp_toolset import MCPToolset, SseServerParams

gitlab_tools = MCPToolset(
    connection_params=SseServerParams(
        url="http://localhost:8000/sse",
        headers={"GITLAB_TOKEN": os.getenv("GITLAB_TOKEN")},
    )
)

💬 Usage Examples

Control GitLab through natural language commands:

Project Management:

"Create a new private project called 'microservice-api'"
"Fork the kubernetes/dashboard project to my namespace"
"Archive the old legacy-system project"

Issue & Code Review:

"Show all open issues in the backend-service project"
"Create merge request from feature/auth-system to main branch"
"Merge the approved MR #23 in mobile-app project"

Repository Operations:

"Create a new config.yaml file with database configuration"
"Show all branches in the web-application project"
"Clone the microservices-platform project to ./local-dev"

CI/CD & Teams:

"Show running pipelines for the deployment project"
"List all my GitLab groups and their members"

🔧 Authentication Setup

GitLab Personal Access Token

Go to GitLab → Settings → Access Tokens
Create token with these scopes:
- ✅ api - Full API access
- ✅ read_repository - Read repository data
- ✅ write_repository - Write repository data
- ✅ read_user - Read user information
Copy the generated token

Environment Variables

Variable	Description	Default
`GITLAB_TOKEN`	Personal Access Token	Required
`GITLAB_URL`	GitLab instance URL	`https://gitlab.com`

🔒 Security Best Practices

Never commit tokens to version control
Use environment variables for token storage
Set token expiration dates when possible
Rotate tokens regularly for enhanced security
Use minimal required scopes for your use case

🐛 Troubleshooting

Token Issues:

❌ GITLAB_TOKEN not set → Set environment variable or provide in headers
❌ 401 Unauthorized → Check token permissions and validity
❌ 403 Forbidden → Verify project access permissions

Git Operations:

❌ Git command not found → Install Git and add to PATH

Test Connection:

curl -H "PRIVATE-TOKEN: your_token" "https://gitlab.com/api/v4/user"

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Made with ❤️ for the GitLab and MCP community

GitLab MCP Server

GitLab MCP Server

🚀 Quick Start

🔌 Transport Options

✨ Key Features

🛠️ Available Tools (46 Total)

📁 Project Management (12 tools)

📝 Issue Management (4 tools)

🔀 Merge Request Management (2 tools)

📄 File Operations (5 tools)

🌿 Repository & Git Operations (15 tools)

🚀 CI/CD Operations (3 tools)

👥 Groups & Collaboration (3 tools)

Installation

Using uvx (Recommended)

Using uv

From source

Setup

Configuration

Claude Desktop Configuration

Using stdio transport (recommended)

Using HTTP transport

Headers Integration

💬 Usage Examples

🔧 Authentication Setup

GitLab Personal Access Token

Environment Variables

🔒 Security Best Practices

🐛 Troubleshooting

🤝 Contributing

📄 License

🔗 Related Projects

GitLab MCP Server

🚀 Quick Start

🔌 Transport Options

✨ Key Features

🛠️ Available Tools (46 Total)

📁 Project Management (12 tools)

📝 Issue Management (4 tools)

🔀 Merge Request Management (2 tools)

📄 File Operations (5 tools)

🌿 Repository & Git Operations (15 tools)

🚀 CI/CD Operations (3 tools)

👥 Groups & Collaboration (3 tools)

Installation

Using uvx (Recommended)

Using uv

From source

Setup

Configuration

Claude Desktop Configuration

Using stdio transport (recommended)

Using HTTP transport

Headers Integration

💬 Usage Examples

🔧 Authentication Setup

GitLab Personal Access Token

Environment Variables

🔒 Security Best Practices

🐛 Troubleshooting

🤝 Contributing

📄 License

🔗 Related Projects