GitLab MCP Server

@zereight/mcp-gitlab

GitLab MCP(Model Context Protocol) Server. Includes bug fixes and improvements over the original GitLab MCP server.

Usage

Using with Claude App, Cline, Roo Code, Cursor

When using with the Claude App, you need to set up your API key and URLs directly.

npx

{
  "mcpServers": {
    "GitLab communication server": {
      "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

{
  "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",
        ...
      }
    }
  }
}

Docker

• stdio mcp.json

{
  "mcpServers": {
    "GitLab communication server": {
      "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

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

{
  "mcpServers": {
    "GitLab communication server": {
      "type": "sse",
      "url": "http://localhost:3333/sse"
    }
  }
}

• streamable-http

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

{
  "mcpServers": {
    "GitLab communication server": {
      "url": "http://localhost:3333/mcp"
    }
  }
}

Docker Image Push

$ sh scripts/image_push.sh docker_user_name

Environment Variables

• GITLAB_PERSONAL_ACCESS_TOKEN: Your GitLab personal access token.
• 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.
• 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, get_pipeline_job, get_pipeline_job_output, create_pipeline, retry_pipeline, cancel_pipeline). 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.

Tools 🛠️

+

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. list_merge_requests - List merge requests in a GitLab project with filtering options
68. list_milestones - List milestones in a GitLab project with filtering options
69. get_milestone - Get details of a specific milestone
70. create_milestone - Create a new milestone in a GitLab project
71. edit_milestone - Edit an existing milestone in a GitLab project
72. delete_milestone - Delete a milestone from a GitLab project
73. get_milestone_issue - Get issues associated with a specific milestone
74. get_milestone_merge_requests - Get merge requests associated with a specific milestone
75. promote_milestone - Promote a milestone to the next stage
76. get_milestone_burndown_events - Get burndown events for a specific milestone
77. get_users - Get GitLab user details by usernames
78. list_commits - List repository commits with filtering options
79. get_commit - Get details of a specific commit
80. get_commit_diff - Get changes/diffs of a specific commit
81. list_group_iterations - List group iterations with filtering options
82. upload_markdown - Upload a file to a GitLab project for use in markdown content
83. download_attachment - Download an uploaded file from a GitLab project by secret and filename