gitlab mcp

# GitLab MCP Server [](https://www.star-history.com/#zereight/gitlab-mcp&Date) ## @zereight/mcp-gitlab [](https://smithery.ai/server/@zereight/gitlab-mcp) GitLab MCP(Model Context Protocol) Server. **Includes bug fixes and improvements over the original GitLab MCP server.** <a href="https://glama.ai/mcp/servers/7jwbk4r6d7"><img width="380" height="200" src="https://glama.ai/mcp/servers/7jwbk4r6d7/badge" alt="gitlab mcp MCP server" /></a> ## Usage ### Using with Claude App, Cline, Roo Code, Cursor, Kilo Code When using with the Claude App, you need to set up your API key and URLs directly. #### npx ```json { "mcpServers": { "gitlab": { "command": "npx", "args": ["-y", "@zereight/mcp-gitlab"], "env": { "GITLAB_PERSONAL_ACCESS_TOKEN": "your_gitlab_token", "GITLAB_API_URL": "your_gitlab_api_url", "GITLAB_PROJECT_ID": "your_project_id", // Optional: default project "GITLAB_ALLOWED_PROJECT_IDS": "", // Optional: comma-separated list of allowed project IDs "GITLAB_READ_ONLY_MODE": "false", "USE_GITLAB_WIKI": "false", // use wiki api? "USE_MILESTONE": "false", // use milestone api? "USE_PIPELINE": "false" // use pipeline api? } } } } ``` #### vscode .vscode/mcp.json ```json { "inputs": [ { "type": "promptString", "id": "gitlab-token", "description": "Gitlab Token to read API", "password": true } ], "servers": { "GitLab-MCP": { "type": "stdio", "command": "npx", "args": ["-y", "@zereight/mcp-gitlab"], "env": { "GITLAB_PERSONAL_ACCESS_TOKEN": "${input:gitlab-token}", "GITLAB_API_URL": "your-fancy-gitlab-url", "GITLAB_READ_ONLY_MODE": "true", ... } } } } ``` #### Strands Agents SDK (MCP Tools) ```python env_vars = { "GITLAB_PERSONAL_ACCESS_TOKEN": gitlab_access_token, "GITLAB_API_URL": gitlab_api_url, "USE_GITLAB_WIKI": use_gitlab_wiki # ......the rest of the optional parameters } stdio_gitlab_mcp_client = MCPClient( lambda: stdio_client( StdioServerParameters( command="npx", args=["-y", "@zereight/mcp-gitlab"], env=env_vars, ) ) ) ``` #### Docker - stdio mcp.json ```json { "mcpServers": { "gitlab": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "GITLAB_PERSONAL_ACCESS_TOKEN", "-e", "GITLAB_API_URL", "-e", "GITLAB_READ_ONLY_MODE", "-e", "USE_GITLAB_WIKI", "-e", "USE_MILESTONE", "-e", "USE_PIPELINE", "iwakitakuma/gitlab-mcp" ], "env": { "GITLAB_PERSONAL_ACCESS_TOKEN": "your_gitlab_token", "GITLAB_API_URL": "https://gitlab.com/api/v4", // Optional, for self-hosted GitLab "GITLAB_READ_ONLY_MODE": "false", "USE_GITLAB_WIKI": "true", "USE_MILESTONE": "true", "USE_PIPELINE": "true" } } } } ``` - sse ```shell docker run -i --rm \ -e GITLAB_PERSONAL_ACCESS_TOKEN=your_gitlab_token \ -e GITLAB_API_URL="https://gitlab.com/api/v4" \ -e GITLAB_READ_ONLY_MODE=true \ -e USE_GITLAB_WIKI=true \ -e USE_MILESTONE=true \ -e USE_PIPELINE=true \ -e SSE=true \ -p 3333:3002 \ iwakitakuma/gitlab-mcp ``` ```json { "mcpServers": { "gitlab": { "type": "sse", "url": "http://localhost:3333/sse" } } } ``` - streamable-http ```shell docker run -i --rm \ -e GITLAB_PERSONAL_ACCESS_TOKEN=your_gitlab_token \ -e GITLAB_API_URL="https://gitlab.com/api/v4" \ -e GITLAB_READ_ONLY_MODE=true \ -e USE_GITLAB_WIKI=true \ -e USE_MILESTONE=true \ -e USE_PIPELINE=true \ -e STREAMABLE_HTTP=true \ -p 3333:3002 \ iwakitakuma/gitlab-mcp ``` ```json { "mcpServers": { "gitlab": { "type": "streamable-http", "url": "http://localhost:3333/mcp" } } } ``` ### Environment Variables #### Authentication Configuration - `GITLAB_PERSONAL_ACCESS_TOKEN`: Your GitLab personal access token. **Required in standard mode**; not used when `REMOTE_AUTHORIZATION=true`. - `REMOTE_AUTHORIZATION`: When set to 'true', enables remote per-session authorization via HTTP headers. In this mode: - The server accepts GitLab PAT tokens from HTTP headers (`Authorization: Bearer <token>` or `Private-Token: <token>`) on a per-session basis - `GITLAB_PERSONAL_ACCESS_TOKEN` environment variable is **not required** and ignored - Only works with **Streamable HTTP transport** (`STREAMABLE_HTTP=true`) because session management was already handled by the transport layer - **SSE transport is disabled** - attempting to use SSE with remote authorization will cause the server to exit with an error - Each client session can use a different token, enabling multi-user support with secure session isolation - Tokens are stored per session and automatically cleaned up when sessions close or timeout - `SESSION_TIMEOUT_SECONDS`: Session auth token timeout in seconds. Default: `3600` (1 hour). Valid range: 1-86400 seconds (recommended: 60+). After this period of inactivity, the auth token is removed but the transport session remains active. The client must provide auth headers again on the next request. Only applies when `REMOTE_AUTHORIZATION=true`. #### Server Configuration - `GITLAB_API_URL`: Your GitLab API URL. (Default: `https://gitlab.com/api/v4`) - `GITLAB_PROJECT_ID`: Default project ID. If set, Overwrite this value when making an API request. - `GITLAB_ALLOWED_PROJECT_IDS`: Optional comma-separated list of allowed project IDs. When set with a single value, acts as a default project (like the old "lock" mode). When set with multiple values, restricts access to only those projects. Examples: - Single value `123`: MCP server can only access project 123 and uses it as default - Multiple values `123,456,789`: MCP server can access projects 123, 456, and 789 but requires explicit project ID in requests - `GITLAB_READ_ONLY_MODE`: When set to 'true', restricts the server to only expose read-only operations. Useful for enhanced security or when write access is not needed. Also useful for using with Cursor and it's 40 tool limit. - `GITLAB_DENIED_TOOLS_REGEX`: When set as a regular expression, it excludes the matching tools. - `USE_GITLAB_WIKI`: When set to 'true', enables the wiki-related tools (list_wiki_pages, get_wiki_page, create_wiki_page, update_wiki_page, delete_wiki_page). By default, wiki features are disabled. - `USE_MILESTONE`: When set to 'true', enables the milestone-related tools (list_milestones, get_milestone, create_milestone, edit_milestone, delete_milestone, get_milestone_issue, get_milestone_merge_requests, promote_milestone, get_milestone_burndown_events). By default, milestone features are disabled. - `USE_PIPELINE`: When set to 'true', enables the pipeline-related tools (list_pipelines, get_pipeline, list_pipeline_jobs, list_pipeline_trigger_jobs, get_pipeline_job, get_pipeline_job_output, create_pipeline, retry_pipeline, cancel_pipeline, play_pipeline_job, retry_pipeline_job, cancel_pipeline_job). By default, pipeline features are disabled. - `GITLAB_AUTH_COOKIE_PATH`: Path to an authentication cookie file for GitLab instances that require cookie-based authentication. When provided, the cookie will be included in all GitLab API requests. - `SSE`: When set to 'true', enables the Server-Sent Events transport. - `STREAMABLE_HTTP`: When set to 'true', enables the Streamable HTTP transport. If both **SSE** and **STREAMABLE_HTTP** are set to 'true', the server will prioritize Streamable HTTP over SSE transport. - `GITLAB_COMMIT_FILES_PER_PAGE`: The number of files per page that GitLab returns for commit diffs. This value should match the server-side GitLab setting. Adjust this if your GitLab instance uses a custom per-page value for commit diffs. #### Performance & Security Configuration - `MAX_SESSIONS`: Maximum number of concurrent sessions allowed. Default: `1000`. Valid range: 1-10000. When limit is reached, new connections are rejected with HTTP 503. - `MAX_REQUESTS_PER_MINUTE`: Rate limit per session in requests per minute. Default: `60`. Valid range: 1-1000. Exceeded requests return HTTP 429. - `PORT`: Server port. Default: `3002`. Valid range: 1-65535. #### Monitoring Endpoints When using Streamable HTTP transport, the following endpoints are available: - `/health`: Health check endpoint returning server status, active sessions count, and uptime. - `/metrics`: Detailed metrics including: - Active and total session counts - Authentication metrics (failures, expirations) - Rate limiting statistics - Resource usage (memory, uptime) - Configuration summary ### Remote Authorization Setup (Multi-User Support) When using `REMOTE_AUTHORIZATION=true`, the MCP server can support multiple users, each with their own GitLab token passed via HTTP headers. This is useful for: - Shared MCP server instances where each user needs their own GitLab access - IDE integrations that can inject user-specific tokens into MCP requests **Setup Example:** ```bash # Start server with remote authorization docker run -d \ -e STREAMABLE_HTTP=true \ -e REMOTE_AUTHORIZATION=true \ -e GITLAB_API_URL="https://gitlab.com/api/v4" \ -e GITLAB_READ_ONLY_MODE=true \ -e SESSION_TIMEOUT_SECONDS=3600 \ -p 3333:3002 \ iwakitakuma/gitlab-mcp ``` **Client Configuration:** Your IDE or MCP client must send one of these headers with each request: ``` Authorization: Bearer glpat-xxxxxxxxxxxxxxxxxxxx ``` or ``` Private-Token: glpat-xxxxxxxxxxxxxxxxxxxx ``` The token is stored per session (identified by `mcp-session-id` header) and reused for subsequent requests in the same session. #### Remote Authorization Client Configuration Example with Cursor ```json { "mcpServers": { "GitLab": { "url": "http(s)://<your_mcp_gitlab_server>/mcp", "headers": { "Authorization": "Bearer glpat-..." } } } } ``` **Important Notes:** - Remote authorization **only works with Streamable HTTP transport** - Each session is isolated - tokens from one session cannot access another session's data Tokens are automatically cleaned up when sessions close - **Session timeout:** Auth tokens expire after `SESSION_TIMEOUT_SECONDS` (default 1 hour) of inactivity. After timeout, the client must send auth headers again. The transport session remains active. - Each request resets the timeout timer for that session - **Rate limiting:** Each session is limited to `MAX_REQUESTS_PER_MINUTE` requests per minute (default 60) - **Capacity limit:** Server accepts up to `MAX_SESSIONS` concurrent sessions (default 1000) ## Tools 🛠️ <details> <summary>Click to expand</summary> <!-- TOOLS-START --> 1. `merge_merge_request` - Merge a merge request in a GitLab project 2. `create_or_update_file` - Create or update a single file in a GitLab project 3. `search_repositories` - Search for GitLab projects 4. `create_repository` - Create a new GitLab project 5. `get_file_contents` - Get the contents of a file or directory from a GitLab project 6. `push_files` - Push multiple files to a GitLab project in a single commit 7. `create_issue` - Create a new issue in a GitLab project 8. `create_merge_request` - Create a new merge request in a GitLab project 9. `fork_repository` - Fork a GitLab project to your account or specified namespace 10. `create_branch` - Create a new branch in a GitLab project 11. `get_merge_request` - Get details of a merge request (Either mergeRequestIid or branchName must be provided) 12. `get_merge_request_diffs` - Get the changes/diffs of a merge request (Either mergeRequestIid or branchName must be provided) 13. `list_merge_request_diffs` - List merge request diffs with pagination support (Either mergeRequestIid or branchName must be provided) 14. `get_branch_diffs` - Get the changes/diffs between two branches or commits in a GitLab project 15. `update_merge_request` - Update a merge request (Either mergeRequestIid or branchName must be provided) 16. `create_note` - Create a new note (comment) to an issue or merge request 17. `create_merge_request_thread` - Create a new thread on a merge request 18. `mr_discussions` - List discussion items for a merge request 19. `update_merge_request_note` - Modify an existing merge request thread note 20. `create_merge_request_note` - Add a new note to an existing merge request thread 21. `get_draft_note` - Get a single draft note from a merge request 22. `list_draft_notes` - List draft notes for a merge request 23. `create_draft_note` - Create a draft note for a merge request 24. `update_draft_note` - Update an existing draft note 25. `delete_draft_note` - Delete a draft note 26. `publish_draft_note` - Publish a single draft note 27. `bulk_publish_draft_notes` - Publish all draft notes for a merge request 28. `update_issue_note` - Modify an existing issue thread note 29. `create_issue_note` - Add a new note to an existing issue thread 30. `list_issues` - List issues (default: created by current user only; use scope='all' for all accessible issues) 31. `my_issues` - List issues assigned to the authenticated user (defaults to open issues) 32. `get_issue` - Get details of a specific issue in a GitLab project 33. `update_issue` - Update an issue in a GitLab project 34. `delete_issue` - Delete an issue from a GitLab project 35. `list_issue_links` - List all issue links for a specific issue 36. `list_issue_discussions` - List discussions for an issue in a GitLab project 37. `get_issue_link` - Get a specific issue link 38. `create_issue_link` - Create an issue link between two issues 39. `delete_issue_link` - Delete an issue link 40. `list_namespaces` - List all namespaces available to the current user 41. `get_namespace` - Get details of a namespace by ID or path 42. `verify_namespace` - Verify if a namespace path exists 43. `get_project` - Get details of a specific project 44. `list_projects` - List projects accessible by the current user 45. `list_project_members` - List members of a GitLab project 46. `list_labels` - List labels for a project 47. `get_label` - Get a single label from a project 48. `create_label` - Create a new label in a project 49. `update_label` - Update an existing label in a project 50. `delete_label` - Delete a label from a project 51. `list_group_projects` - List projects in a GitLab group with filtering options 52. `list_wiki_pages` - List wiki pages in a GitLab project 53. `get_wiki_page` - Get details of a specific wiki page 54. `create_wiki_page` - Create a new wiki page in a GitLab project 55. `update_wiki_page` - Update an existing wiki page in a GitLab project 56. `delete_wiki_page` - Delete a wiki page from a GitLab project 57. `get_repository_tree` - Get the repository tree for a GitLab project (list files and directories) 58. `list_pipelines` - List pipelines in a GitLab project with filtering options 59. `get_pipeline` - Get details of a specific pipeline in a GitLab project 60. `list_pipeline_jobs` - List all jobs in a specific pipeline 61. `list_pipeline_trigger_jobs` - List all trigger jobs (bridges) in a specific pipeline that trigger downstream pipelines 62. `get_pipeline_job` - Get details of a GitLab pipeline job number 63. `get_pipeline_job_output` - Get the output/trace of a GitLab pipeline job with optional pagination to limit context window usage 64. `create_pipeline` - Create a new pipeline for a branch or tag 65. `retry_pipeline` - Retry a failed or canceled pipeline 66. `cancel_pipeline` - Cancel a running pipeline 67. `play_pipeline_job` - Run a manual pipeline job 68. `retry_pipeline_job` - Retry a failed or canceled pipeline job 69. `cancel_pipeline_job` - Cancel a running pipeline job 70. `list_merge_requests` - List merge requests in a GitLab project with filtering options 71. `list_milestones` - List milestones in a GitLab project with filtering options 72. `get_milestone` - Get details of a specific milestone 73. `create_milestone` - Create a new milestone in a GitLab project 74. `edit_milestone` - Edit an existing milestone in a GitLab project 75. `delete_milestone` - Delete a milestone from a GitLab project 76. `get_milestone_issue` - Get issues associated with a specific milestone 77. `get_milestone_merge_requests` - Get merge requests associated with a specific milestone 78. `promote_milestone` - Promote a milestone to the next stage 79. `get_milestone_burndown_events` - Get burndown events for a specific milestone 80. `get_users` - Get GitLab user details by usernames 81. `list_commits` - List repository commits with filtering options 82. `get_commit` - Get details of a specific commit 83. `get_commit_diff` - Get changes/diffs of a specific commit 84. `list_group_iterations` - List group iterations with filtering options 85. `upload_markdown` - Upload a file to a GitLab project for use in markdown content 86. `download_attachment` - Download an uploaded file from a GitLab project by secret and filename 87. `list_events` - List all events for the currently authenticated user 88. `get_project_events` - List all visible events for a specified project 89. `list_releases` - List all releases for a project 90. `get_release` - Get a release by tag name 91. `create_release` - Create a new release in a GitLab project 92. `update_release` - Update an existing release in a GitLab project 93. `delete_release` - Delete a release from a GitLab project (does not delete the associated tag) 94. `create_release_evidence` - Create release evidence for an existing release (GitLab Premium/Ultimate only) 95. `download_release_asset` - Download a release asset file by direct asset path <!-- TOOLS-END --> </details> ## Testing 🧪 The project includes comprehensive test coverage including remote authorization: ```bash # Run all tests (API validation + remote auth) npm test # Run only remote authorization tests npm run test:remote-auth # Run all tests including readonly MCP tests npm run test:all # Run only API validation npm run test:integration ``` All remote authorization tests use a mock GitLab server and do not require actual GitLab credentials.