# GitLab MCP Server
[](https://badge.fury.io/py/gitlab-clone-mcp-server)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
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
```bash
# 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:
```bash
# 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](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)
```bash
uvx --from gitlab-clone-mcp-server gitlab-mcp
```
### Using uv
```bash
uv tool install gitlab-mcp-server
```
### From source
```bash
git clone <repository-url>
cd gitlab-mcp
uv sync
```
## Setup
1. Get GitLab Personal Access Token:
- Go to GitLab → Settings → Access Tokens
- Create token with `api` scope
- Copy the token
2. Set environment variables:
```bash
export GITLAB_TOKEN="your_token_here"
export GITLAB_URL="https://gitlab.com" # optional
```
3. Test the server:
```bash
gitlab-mcp
```
## Configuration
### Claude Desktop Configuration
Add to your Claude Desktop config (`%APPDATA%\Claude\claude_desktop_config.json`):
#### Using stdio transport (recommended)
```json
{
"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:
```json
{
"mcpServers": {
"gitlab": {
"url": "http://localhost:8000/mcp",
"headers": {
"GITLAB_TOKEN": "your_gitlab_token_here"
}
}
}
}
```
### Headers Integration
For applications using MCPToolset, connect with headers:
```python
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
1. Go to GitLab → Settings → Access Tokens
2. Create token with these scopes:
- ✅ `api` - Full API access
- ✅ `read_repository` - Read repository data
- ✅ `write_repository` - Write repository data
- ✅ `read_user` - Read user information
3. 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:**
```bash
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](LICENSE) file for details.
## 🔗 Related Projects
- [Model Context Protocol](https://github.com/modelcontextprotocol/python-sdk)
- [Claude Desktop](https://claude.ai/desktop)
- [GitLab API Documentation](https://docs.gitlab.com/ee/api/)
---
**Made with ❤️ for the GitLab and MCP community**
Raw data
{
"_id": null,
"home_page": null,
"name": "gitlab-clone-mcp-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "api, gitlab, mcp, server",
"author": null,
"author_email": "GitLab MCP <gitlab-mcp@example.com>",
"download_url": "https://files.pythonhosted.org/packages/d3/1e/3cbcb7b1d31c6e3fa0e1303f61a3ea77b8ffbdefa3c1efbca547909741d1/gitlab_clone_mcp_server-1.1.0.tar.gz",
"platform": null,
"description": "# GitLab MCP Server\n\n[](https://badge.fury.io/py/gitlab-clone-mcp-server)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n\nA 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.\n\n## \ud83d\ude80 Quick Start\n\n```bash\n# Install with uvx (recommended)\nuvx --from gitlab-clone-mcp-server gitlab-mcp\n\n# Or install as a tool\nuv tool install gitlab-clone-mcp-server\n```\n\n## \ud83d\udd0c Transport Options\n\nGitLab MCP Server supports three transport types:\n\n```bash\n# Run with stdio transport (default)\ngitlab-mcp stdio\n\n# Run with SSE transport\ngitlab-mcp sse --host localhost --port 8000\n\n# Run with Streamable HTTP transport (recommended for production)\ngitlab-mcp streamable-http --host localhost --port 8000\n```\n\nSee [TRANSPORT_OPTIONS.md](TRANSPORT_OPTIONS.md) for detailed configuration.\n\n## \u2728 Key Features\n\n- **Complete GitLab Integration**: 46+ tools covering all major GitLab operations\n- **Natural Language Interface**: Control GitLab through conversational commands\n- **Zero Configuration**: Works out-of-the-box with your GitLab Personal Access Token\n- **Comprehensive Coverage**: Projects, repositories, issues, merge requests, CI/CD, and more\n- **Local Repository Cloning**: Clone repositories directly to your local machine\n- **Batch Operations**: Perform bulk operations across multiple projects\n\n## \ud83d\udee0\ufe0f Available Tools (46 Total)\n\n### \ud83d\udcc1 Project Management (12 tools)\n| Tool | Description |\n|------|-------------|\n| `create_project` | Create new GitLab projects with custom settings |\n| `delete_project` | Permanently delete GitLab projects |\n| `update_project` | Modify project name, description, visibility |\n| `fork_project` | Fork projects to different namespaces |\n| `archive_project` | Archive projects for long-term storage |\n| `unarchive_project` | Restore archived projects |\n| `list_projects` | List all accessible projects with filters |\n| `search_projects` | Search projects by name or keywords |\n| `get_project_milestones` | View project milestones and deadlines |\n| `get_project_labels` | List all project labels and colors |\n| `list_project_hooks` | View configured webhooks |\n| `get_current_user` | Get current user information and permissions |\n\n### \ud83d\udcdd Issue Management (4 tools)\n| Tool | Description |\n|------|-------------|\n| `get_project_issues` | List issues with state filtering |\n| `create_issue` | Create new issues with descriptions |\n| `update_issue` | Modify issue title, description, state |\n| `close_issue` | Close specific issues |\n\n### \ud83d\udd00 Merge Request Management (2 tools)\n| Tool | Description |\n|------|-------------|\n| `get_merge_requests` | List merge requests by state |\n| `create_merge_request` | Create new merge requests |\n| `merge_merge_request` | Merge approved merge requests |\n\n### \ud83d\udcc4 File Operations (5 tools)\n| Tool | Description |\n|------|-------------|\n| `create_file` | Create new files with content |\n| `update_file` | Modify existing file content |\n| `delete_file` | Remove files from repository |\n| `get_file_content` | Read file contents |\n| `get_repository_files` | Browse directory structures |\n\n### \ud83c\udf3f Repository & Git Operations (15 tools)\n| Tool | Description |\n|------|-------------|\n| `get_project_branches` | List all repository branches |\n| `create_branch` | Create new branches from any reference |\n| `delete_branch` | Remove branches safely |\n| `get_commits` | View commit history |\n| `create_commit` | Create commits with multiple file changes |\n| `compare_branches` | Compare differences between branches |\n| `revert_commit` | Revert specific commits |\n| `cherry_pick_commit` | Cherry-pick commits between branches |\n| `get_repository_tags` | List all repository tags |\n| `create_tag` | Create release tags |\n| `delete_tag` | Remove tags |\n| `clone_repository` | Clone single repository locally |\n| `clone_group_repositories` | Batch clone all group repositories |\n\n### \ud83d\ude80 CI/CD Operations (3 tools)\n| Tool | Description |\n|------|-------------|\n| `get_pipelines` | Monitor pipeline status |\n| `get_pipeline_jobs` | View individual job details |\n| `trigger_pipeline` | Start new pipeline runs |\n\n### \ud83d\udc65 Groups & Collaboration (3 tools)\n| Tool | Description |\n|------|-------------|\n| `list_groups` | List accessible GitLab groups |\n| `get_group_members` | View group membership |\n| `get_current_user` | Get user profile information |\n\n## Installation\n\n### Using uvx (Recommended)\n```bash\nuvx --from gitlab-clone-mcp-server gitlab-mcp\n```\n\n### Using uv\n```bash\nuv tool install gitlab-mcp-server\n```\n\n### From source\n```bash\ngit clone <repository-url>\ncd gitlab-mcp\nuv sync\n```\n\n## Setup\n\n1. Get GitLab Personal Access Token:\n - Go to GitLab \u2192 Settings \u2192 Access Tokens\n - Create token with `api` scope\n - Copy the token\n\n2. Set environment variables:\n ```bash\n export GITLAB_TOKEN=\"your_token_here\"\n export GITLAB_URL=\"https://gitlab.com\" # optional\n ```\n\n3. Test the server:\n ```bash\n gitlab-mcp\n ```\n\n## Configuration\n\n### Claude Desktop Configuration\n\nAdd to your Claude Desktop config (`%APPDATA%\\Claude\\claude_desktop_config.json`):\n\n#### Using stdio transport (recommended)\n\n```json\n{\n \"mcpServers\": {\n \"gitlab\": {\n \"command\": \"uvx\",\n \"args\": [\n \"--from\", \"gitlab-clone-mcp-server\",\n \"gitlab-mcp\", \"stdio\"\n ],\n \"env\": {\n \"GITLAB_URL\": \"https://gitlab.com\",\n \"GITLAB_TOKEN\": \"your_gitlab_token_here\"\n }\n }\n }\n}\n```\n\n#### Using HTTP transport\n\nIf you're running the server with Streamable HTTP transport:\n\n```json\n{\n \"mcpServers\": {\n \"gitlab\": {\n \"url\": \"http://localhost:8000/mcp\",\n \"headers\": {\n \"GITLAB_TOKEN\": \"your_gitlab_token_here\"\n }\n }\n }\n}\n```\n\n### Headers Integration\n\nFor applications using MCPToolset, connect with headers:\n\n```python\nimport os\nfrom mcp_toolset import MCPToolset, SseServerParams\n\ngitlab_tools = MCPToolset(\n connection_params=SseServerParams(\n url=\"http://localhost:8000/sse\",\n headers={\"GITLAB_TOKEN\": os.getenv(\"GITLAB_TOKEN\")},\n )\n)\n```\n\n## \ud83d\udcac Usage Examples\n\nControl GitLab through natural language commands:\n\n**Project Management:**\n- \"Create a new private project called 'microservice-api'\"\n- \"Fork the kubernetes/dashboard project to my namespace\"\n- \"Archive the old legacy-system project\"\n\n**Issue & Code Review:**\n- \"Show all open issues in the backend-service project\"\n- \"Create merge request from feature/auth-system to main branch\"\n- \"Merge the approved MR #23 in mobile-app project\"\n\n**Repository Operations:**\n- \"Create a new config.yaml file with database configuration\"\n- \"Show all branches in the web-application project\"\n- \"Clone the microservices-platform project to ./local-dev\"\n\n**CI/CD & Teams:**\n- \"Show running pipelines for the deployment project\"\n- \"List all my GitLab groups and their members\"\n\n## \ud83d\udd27 Authentication Setup\n\n### GitLab Personal Access Token\n\n1. Go to GitLab \u2192 Settings \u2192 Access Tokens\n2. Create token with these scopes:\n - \u2705 `api` - Full API access\n - \u2705 `read_repository` - Read repository data\n - \u2705 `write_repository` - Write repository data\n - \u2705 `read_user` - Read user information\n3. Copy the generated token\n\n### Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|----------|\n| `GITLAB_TOKEN` | Personal Access Token | Required |\n| `GITLAB_URL` | GitLab instance URL | `https://gitlab.com` |\n\n## \ud83d\udd12 Security Best Practices\n\n- **Never commit tokens** to version control\n- **Use environment variables** for token storage\n- **Set token expiration** dates when possible\n- **Rotate tokens regularly** for enhanced security\n- **Use minimal required scopes** for your use case\n\n## \ud83d\udc1b Troubleshooting\n\n**Token Issues:**\n- \u274c `GITLAB_TOKEN not set` \u2192 Set environment variable or provide in headers\n- \u274c `401 Unauthorized` \u2192 Check token permissions and validity\n- \u274c `403 Forbidden` \u2192 Verify project access permissions\n\n**Git Operations:**\n- \u274c `Git command not found` \u2192 Install Git and add to PATH\n\n**Test Connection:**\n```bash\ncurl -H \"PRIVATE-TOKEN: your_token\" \"https://gitlab.com/api/v4/user\"\n```\n\n## \ud83e\udd1d Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\udd17 Related Projects\n\n- [Model Context Protocol](https://github.com/modelcontextprotocol/python-sdk)\n- [Claude Desktop](https://claude.ai/desktop)\n- [GitLab API Documentation](https://docs.gitlab.com/ee/api/)\n\n---\n\n**Made with \u2764\ufe0f for the GitLab and MCP community**",
"bugtrack_url": null,
"license": "MIT",
"summary": "Model Context Protocol server for GitLab API integration",
"version": "1.1.0",
"project_urls": {
"Homepage": "https://github.com/skmprb/gitlab-clone-mcp-server",
"Issues": "https://github.com/skmprb/gitlab-clone-mcp-server/issues",
"Repository": "https://github.com/skmprb/gitlab-clone-mcp-server"
},
"split_keywords": [
"api",
" gitlab",
" mcp",
" server"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b73f111075ccb2001756daa09d602d053168c367db23bb9aad863906ee25db07",
"md5": "1323b42b7f539d761ff3d9e553bff944",
"sha256": "f6814553abcc8036cd8dab38f6943f61e98825c061e3d1724678e86d7fe21ed7"
},
"downloads": -1,
"filename": "gitlab_clone_mcp_server-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1323b42b7f539d761ff3d9e553bff944",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 13777,
"upload_time": "2025-07-23T12:17:45",
"upload_time_iso_8601": "2025-07-23T12:17:45.536636Z",
"url": "https://files.pythonhosted.org/packages/b7/3f/111075ccb2001756daa09d602d053168c367db23bb9aad863906ee25db07/gitlab_clone_mcp_server-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d31e3cbcb7b1d31c6e3fa0e1303f61a3ea77b8ffbdefa3c1efbca547909741d1",
"md5": "aa5596793ee85eb87e86097db5489891",
"sha256": "6b19af93ab23536bede9ecf3a90bcbb3e5ed5f502909bc1726f7f18ed4b6b801"
},
"downloads": -1,
"filename": "gitlab_clone_mcp_server-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "aa5596793ee85eb87e86097db5489891",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 35695,
"upload_time": "2025-07-23T12:17:46",
"upload_time_iso_8601": "2025-07-23T12:17:46.525814Z",
"url": "https://files.pythonhosted.org/packages/d3/1e/3cbcb7b1d31c6e3fa0e1303f61a3ea77b8ffbdefa3c1efbca547909741d1/gitlab_clone_mcp_server-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-23 12:17:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "skmprb",
"github_project": "gitlab-clone-mcp-server",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "mcp",
"specs": [
[
">=",
"1.12.1"
]
]
},
{
"name": "httpx",
"specs": [
[
">=",
"0.25.0"
]
]
},
{
"name": "starlette",
"specs": [
[
">=",
"0.37.0"
]
]
},
{
"name": "uvicorn",
"specs": [
[
">=",
"0.24.0"
]
]
}
],
"lcname": "gitlab-clone-mcp-server"
}
JSON
