Gitlab MCP Server

GitLab MCP Server

New Feature: Dynamic GitLab API URL support with connection pooling! See Dynamic API URL Documentation for details.

@zereight/mcp-gitlab

A comprehensive GitLab MCP server for AI clients. Manage projects, merge requests, issues, pipelines, wiki, releases, milestones, and more through stdio, SSE, and Streamable HTTP.

Supports PAT, OAuth, read-only mode, dynamic API URLs, and remote authorization for VS Code, Claude, Cursor, Copilot, and other MCP clients.

Why use this GitLab MCP?

• Broad GitLab coverage — projects, repository browsing, merge requests, issues, pipelines, wiki, releases, labels, milestones, and more
• Flexible auth — Personal Access Token, local OAuth2 browser flow, MCP OAuth proxy, and per-request remote authorization
• Multiple transports — stdio for local clients, SSE for legacy clients, and Streamable HTTP for modern remote deployments
• Client-friendly setup — examples for Claude Code, Codex, Antigravity, OpenCode, Copilot, Cline, Roo Code, Cursor, Kilo Code, and Amp Code
• Self-hosted ready — works with custom GitLab instances, proxy settings, and dynamic API URL routing

Quick start: choose either Personal Access Token or OAuth2 setup below and use @zereight/mcp-gitlab in your MCP client configuration.

Client Setup Guides

• Claude Code Setup Guide
• VS Code Setup Guide
• GitHub Copilot Setup Guide
• Codex Setup Guide
• Cursor Setup Guide
• JSON-Based MCP Clients Setup Guide - for Factory AI Droid, OpenClaw, and OpenCode style clients
• OAuth2 Authentication Setup Guide
• Environment Variables Reference

Usage

Setup Overview

Authentication Methods

The server supports four authentication methods:

For local/desktop use (most common):

1. Personal Access Token (GITLAB_PERSONAL_ACCESS_TOKEN) — simplest setup
2. OAuth2 — Local Browser (GITLAB_USE_OAUTH) — recommended for better security

For server/remote deployments:

1. OAuth2 — MCP Proxy (GITLAB_MCP_OAUTH) — for remote MCP clients such as Claude.ai
2. Remote Authorization (REMOTE_AUTHORIZATION) — multi-user deployments where each caller provides their own token

Quick setup paths

• Claude Code: see Claude Code Setup Guide
• VS Code: see VS Code Setup Guide
• GitHub Copilot: see GitHub Copilot Setup Guide
• Codex: see Codex Setup Guide
• Cursor: see Cursor Setup Guide
• Factory AI Droid / OpenClaw / OpenCode style clients: see JSON-Based MCP Clients Setup Guide
• OAuth browser flow details: see OAuth2 Authentication Setup Guide

For the simplest local setup, start with a Personal Access Token. For browser-based local auth, use OAuth2. For remote or multi-user deployments, continue to the MCP OAuth and Remote Authorization sections later in this README.

Using CLI Arguments (for clients with env var issues)

Some MCP clients (like GitHub Copilot CLI) have issues with environment variables. Use CLI arguments instead:

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": [
        "-y",
        "@zereight/mcp-gitlab",
        "--token=YOUR_GITLAB_TOKEN",
        "--api-url=https://gitlab.com/api/v4"
      ],
      "tools": ["*"]
    }
  }
}

Available CLI arguments:

• --token - GitLab Personal Access Token (replaces GITLAB_PERSONAL_ACCESS_TOKEN)
• --api-url - GitLab API URL (replaces GITLAB_API_URL)
• --read-only=true - Enable read-only mode (replaces GITLAB_READ_ONLY_MODE)
• --use-wiki=true - Enable wiki API (replaces USE_GITLAB_WIKI)
• --use-milestone=true - Enable milestone API (replaces USE_MILESTONE)
• --use-pipeline=true - Enable pipeline API (replaces USE_PIPELINE)

CLI arguments take precedence over environment variables.

• sse

docker run -i --rm \
  -e HOST=0.0.0.0 \
  -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 \
  zereight050/gitlab-mcp

{
  "mcpServers": {
    "gitlab": {
      "type": "sse",
      "url": "http://localhost:3333/sse"
    }
  }
}

• streamable-http

docker run -i --rm \
  -e HOST=0.0.0.0 \
  -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 \
  zereight050/gitlab-mcp

{
  "mcpServers": {
    "gitlab": {
      "type": "streamable-http",
      "url": "http://localhost:3333/mcp"
    }
  }
}

Using MCP OAuth Proxy (GITLAB_MCP_OAUTH)

For server/remote deployments only. This mode requires the MCP server to be deployed with a publicly accessible HTTPS URL. For local/desktop use, see GITLAB_USE_OAUTH above.

For remote MCP clients that support the MCP OAuth specification (e.g. Claude.ai). The server acts as a full OAuth 2.0 authorization server — unauthenticated requests receive a 401 + WWW-Authenticate response, which triggers the OAuth browser flow automatically on the client side.

How it works: You deploy this MCP server somewhere with a public HTTPS URL. MCP clients connect to {MCP_SERVER_URL}/mcp. The server handles the OAuth 2.0 flow, exchanging credentials with GitLab on behalf of the client.

Prerequisites:

1. A publicly accessible HTTPS server URL (MCP_SERVER_URL) — use ngrok for local testing
2. A pre-registered GitLab OAuth application with api (or read_api) scopes — Go to Admin area → Applications, set Redirect URI to {MCP_SERVER_URL}/callback

docker run -i --rm \
  -e HOST=0.0.0.0 \
  -e GITLAB_MCP_OAUTH=true \
  -e STREAMABLE_HTTP=true \
  -e MCP_SERVER_URL=https://your-server.example.com \
  -e GITLAB_API_URL="https://gitlab.com/api/v4" \
  -e GITLAB_OAUTH_APP_ID=your_app_id \
  -p 3000:3002 \
  zereight050/gitlab-mcp

MCP client configuration:

{
  "mcpServers": {
    "gitlab": {
      "type": "http",
      "url": "https://your-server.example.com/mcp"
    }
  }
}

Using Remote Authorization (REMOTE_AUTHORIZATION)

For server/remote deployments only. Each HTTP caller provides their own GitLab token directly in request headers — no OAuth flow involved.

For multi-user or multi-tenant deployments where each caller provides their own GitLab token in the HTTP request header. No OAuth flow — the MCP server forwards the token to GitLab on behalf of the caller.

Header priority: Private-Token > JOB-TOKEN > Authorization: Bearer

Example request headers:

Private-Token: glpat-xxxxxxxxxxxxxxxxxxxx

or using a Bearer token:

Authorization: Bearer glpat-xxxxxxxxxxxxxxxxxxxx

⚠️ REMOTE_AUTHORIZATION is not compatible with SSE transport. STREAMABLE_HTTP=true is required.

Environment Variables

Use the dedicated reference for the full environment variable list:

• Environment Variables Reference

Most users only need one of these starting sets:

• Local PAT: GITLAB_PERSONAL_ACCESS_TOKEN, GITLAB_API_URL
• Local OAuth: GITLAB_USE_OAUTH=true, GITLAB_OAUTH_CLIENT_ID, GITLAB_OAUTH_REDIRECT_URI, GITLAB_API_URL
• Remote multi-user HTTP: STREAMABLE_HTTP=true, REMOTE_AUTHORIZATION=true, HOST, PORT

Commonly referenced variables:

• GITLAB_API_URL
• GITLAB_PERSONAL_ACCESS_TOKEN
• GITLAB_USE_OAUTH
• REMOTE_AUTHORIZATION
• GITLAB_MCP_OAUTH

The reference document also covers:

• auth and OAuth variables
• MCP OAuth proxy variables
• project and tool filtering variables
• dynamic tool discovery via discover_tools (on-demand toolset activation)
• transport and session variables
• proxy and TLS variables

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:

# Start server with remote authorization
docker run -d \
  -e HOST=0.0.0.0 \
  -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 \
  zereight050/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

{
  "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)

MCP OAuth Setup (Claude.ai Native OAuth)

When using GITLAB_MCP_OAUTH=true, the server acts as an OAuth proxy to your GitLab instance. Claude.ai (and any MCP-spec-compliant client) handles the entire browser authentication flow automatically — no manual Personal Access Token management needed.

Prerequisites:

A pre-registered GitLab OAuth application is required. GitLab restricts dynamically registered (unverified) applications to the mcp scope, which is insufficient for API calls (need api or read_api).

1. Go to your GitLab instance → Admin Area > Applications (instance-wide) or User Settings > Applications (personal)
2. Create a new application with:
   • Confidential: unchecked
   • Scopes: api, read_api, read_user (or whichever scopes you intend to request via GITLAB_OAUTH_SCOPES)
3. Save and copy the Application ID — this is your GITLAB_OAUTH_APP_ID

How it works:

1. User adds your MCP server URL in Claude.ai
2. Claude.ai discovers OAuth endpoints via /.well-known/oauth-authorization-server
3. Claude.ai registers itself via Dynamic Client Registration (POST /register) — handled locally by the MCP server (each client gets a virtual client ID)
4. Claude.ai redirects the user's browser to GitLab's login page using the pre-registered OAuth application
5. User authenticates; GitLab redirects back to https://claude.ai/api/mcp/auth_callback
6. Claude.ai sends Authorization: Bearer <token> on every MCP request
7. Server validates the token with GitLab and stores it per session

Server setup:

docker run -d \
  -e STREAMABLE_HTTP=true \
  -e GITLAB_MCP_OAUTH=true \
  -e GITLAB_OAUTH_APP_ID="your-gitlab-oauth-app-client-id" \
  -e GITLAB_API_URL="https://gitlab.example.com/api/v4" \
  -e MCP_SERVER_URL="https://your-mcp-server.example.com" \
  -p 3002:3002 \
  zereight050/gitlab-mcp

For local development (HTTP allowed):

MCP_DANGEROUSLY_ALLOW_INSECURE_ISSUER_URL=true \
STREAMABLE_HTTP=true \
GITLAB_MCP_OAUTH=true \
GITLAB_OAUTH_APP_ID=your-gitlab-oauth-app-client-id \
MCP_SERVER_URL=http://localhost:3002 \
GITLAB_API_URL=https://gitlab.com/api/v4 \
node build/index.js

Claude.ai configuration:

{
  "mcpServers": {
    "GitLab": {
      "url": "https://your-mcp-server.example.com/mcp"
    }
  }
}

No headers field is needed — Claude.ai obtains the token via OAuth automatically.

Environment variables:

Important Notes:

• MCP OAuth only works with Streamable HTTP transport (SSE=true is incompatible)
• Each user session stores its own OAuth token — sessions are fully isolated
• Session timeout, rate limiting, and capacity limits apply identically to the REMOTE_AUTHORIZATION mode (SESSION_TIMEOUT_SECONDS, MAX_REQUESTS_PER_MINUTE, MAX_SESSIONS)
• Header auth fallback: when Private-Token or JOB-TOKEN request headers are present, OAuth validation is skipped and the raw token is used directly for that session. This allows PATs and CI job tokens to be used alongside the OAuth flow on the same server instance. Authorization: Bearer is always treated as an OAuth token — use Private-Token for PAT-based header auth.

Agent Skill Files

Pre-built skill files are available in skills/gitlab-mcp/ for AI agents that support skill/instruction loading (Claude Code, GitHub Copilot, Cursor, etc.).

• SKILL.md — Core guide (~800 tokens) with toolset overview, key workflows, and parameter hints
• reference/ — Detailed workflow docs for code review, merge requests, issues, and pipelines

Register the skill directory in your AI client to get optimal tool usage guidance without relying solely on the full ListTools response.

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 with compact deployment summary, behind-count, commit addition summary, and approval summary (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_merge_request_conflicts - Get the conflicts of a merge request in a GitLab project
15. list_merge_request_changed_files - STEP 1 of code review workflow. Returns ONLY the list of changed file paths in a merge request — WITHOUT diff content. Call this first to get file paths, then call get_merge_request_file_diff with multiple files in a single batched call (recommended 3-5 files per call). Supports excluded_file_patterns filtering using regex. (Either mergeRequestIid or branchName must be provided)
16. get_merge_request_file_diff - STEP 2 of code review workflow. Get diffs for one or more files from a merge request. Call list_merge_request_changed_files first, then pass them as an array to fetch diffs efficiently. Batching multiple files (recommended 3-5) is supported. (Either mergeRequestIid or branchName must be provided)
17. list_merge_request_versions - List all versions of a merge request
18. get_merge_request_version - Get a specific version of a merge request
19. get_branch_diffs - Get the changes/diffs between two branches or commits in a GitLab project
20. update_merge_request - Update a merge request (Either mergeRequestIid or branchName must be provided)
21. create_note - Create a new note (comment) to an issue or merge request
22. create_merge_request_thread - Create a new thread on a merge request
23. mr_discussions - List discussion items for a merge request
24. resolve_merge_request_thread - Resolve a thread on a merge request
25. update_merge_request_note - Modify an existing merge request thread note
26. create_merge_request_note - Add a new note to an existing merge request thread
27. delete_merge_request_discussion_note - Delete a discussion note on a merge request
28. update_merge_request_discussion_note - Update a discussion note on a merge request
29. create_merge_request_discussion_note - Add a new discussion note to an existing merge request thread
30. delete_merge_request_note - Delete an existing merge request note
31. get_merge_request_note - Get a specific note for a merge request
32. get_merge_request_notes - List notes for a merge request
33. get_draft_note - Get a single draft note from a merge request
34. list_draft_notes - List draft notes for a merge request
35. create_draft_note - Create a draft note for a merge request
36. update_draft_note - Update an existing draft note
37. delete_draft_note - Delete a draft note
38. publish_draft_note - Publish a single draft note
39. bulk_publish_draft_notes - Publish all draft notes for a merge request
40. list_merge_requests - List merge requests globally or in a specific GitLab project with filtering options (project_id is now optional)
41. approve_merge_request - Approve a merge request (requires appropriate permissions)
42. unapprove_merge_request - Unapprove a previously approved merge request
43. get_merge_request_approval_state - Get merge request approval details including approvers (uses approval_state when available, otherwise falls back to approvals)
44. update_issue_note - Modify an existing issue thread note
45. create_issue_note - Add a new note to an existing issue thread
46. list_issues - List issues (default: created by current user only; use scope='all' for all accessible issues)
47. my_issues - List issues assigned to the authenticated user (defaults to open issues)
48. get_issue - Get details of a specific issue in a GitLab project
49. update_issue - Update an issue in a GitLab project
50. delete_issue - Delete an issue from a GitLab project
51. list_issue_links - List all issue links for a specific issue
52. list_issue_discussions - List discussions for an issue in a GitLab project
53. get_issue_link - Get a specific issue link
54. create_issue_link - Create an issue link between two issues
55. delete_issue_link - Delete an issue link
56. list_namespaces - List all namespaces available to the current user
57. get_namespace - Get details of a namespace by ID or path
58. verify_namespace - Verify if a namespace path exists
59. get_project - Get details of a specific project
60. list_projects - List projects accessible by the current user
61. list_project_members - List members of a GitLab project
62. list_group_projects - List projects in a GitLab group with filtering options
63. list_group_iterations - List group iterations with filtering options
64. list_labels - List labels for a project
65. get_label - Get a single label from a project
66. create_label - Create a new label in a project
67. update_label - Update an existing label in a project
68. delete_label - Delete a label from a project
69. list_pipelines - List pipelines in a GitLab project with filtering options
70. get_pipeline - Get details of a specific pipeline in a GitLab project
71. list_pipeline_jobs - List all jobs in a specific pipeline
72. list_pipeline_trigger_jobs - List all trigger jobs (bridges) in a specific pipeline that trigger downstream pipelines
73. get_pipeline_job - Get details of a GitLab pipeline job number
74. get_pipeline_job_output - Get the output/trace of a GitLab pipeline job with optional pagination to limit context window usage
75. create_pipeline - Create a new pipeline for a branch or tag
76. retry_pipeline - Retry a failed or canceled pipeline
77. cancel_pipeline - Cancel a running pipeline
78. play_pipeline_job - Run a manual pipeline job
79. retry_pipeline_job - Retry a failed or canceled pipeline job
80. cancel_pipeline_job - Cancel a running pipeline job
81. list_deployments - List deployments in a GitLab project with filtering options
82. get_deployment - Get details of a specific deployment in a GitLab project
83. list_environments - List environments in a GitLab project
84. get_environment - Get details of a specific environment in a GitLab project
85. list_job_artifacts - List artifact files in a job's artifacts archive. Returns file names, paths, types, and sizes
86. download_job_artifacts - Download the entire artifact archive (zip) for a job to a local path. Returns the saved file path
87. get_job_artifact_file - Get the content of a single file from a job's artifacts by its path within the archive
88. list_milestones - List milestones in a GitLab project with filtering options
89. get_milestone - Get details of a specific milestone
90. create_milestone - Create a new milestone in a GitLab project
91. edit_milestone - Edit an existing milestone in a GitLab project
92. delete_milestone - Delete a milestone from a GitLab project
93. get_milestone_issue - Get issues associated with a specific milestone
94. get_milestone_merge_requests - Get merge requests associated with a specific milestone
95. promote_milestone - Promote a milestone to the next stage
96. get_milestone_burndown_events - Get burndown events for a specific milestone
97. list_wiki_pages - List wiki pages in a GitLab project
98. get_wiki_page - Get details of a specific wiki page
99. create_wiki_page - Create a new wiki page in a GitLab project
100. update_wiki_page - Update an existing wiki page in a GitLab project
101. delete_wiki_page - Delete a wiki page from a GitLab project
102. list_group_wiki_pages - List wiki pages in a GitLab group
103. get_group_wiki_page - Get details of a specific group wiki page
104. create_group_wiki_page - Create a new wiki page in a GitLab group
105. update_group_wiki_page - Update an existing wiki page in a GitLab group
106. delete_group_wiki_page - Delete a wiki page from a GitLab group
107. get_repository_tree - Get the repository tree for a GitLab project (list files and directories)
108. list_commits - List repository commits with filtering options
109. get_commit - Get details of a specific commit
110. get_commit_diff - Get changes/diffs of a specific commit
111. list_releases - List all releases for a project
112. get_release - Get a release by tag name
113. create_release - Create a new release in a GitLab project
114. update_release - Update an existing release in a GitLab project
115. delete_release - Delete a release from a GitLab project (does not delete the associated tag)
116. create_release_evidence - Create release evidence for an existing release (GitLab Premium/Ultimate only)
117. download_release_asset - Download a release asset file by direct asset path
118. get_users - Get GitLab user details by usernames
119. list_events - List all events for the currently authenticated user
120. get_project_events - List all visible events for a specified project
121. upload_markdown - Upload a file to a GitLab project for use in markdown content
122. download_attachment - Download an uploaded file from a GitLab project by secret and filename
123. get_work_item - Get a single work item with full details including status, hierarchy (parent/children), type, labels, assignees, and all widgets
124. list_work_items - List work items in a project with filters (type, state, search, assignees, labels). Returns items with status and hierarchy info
125. create_work_item - Create a new work item (issue, task, incident, test_case, epic, key_result, objective, requirement, ticket). Supports setting title, description, labels, assignees, weight, parent, health status, start/due dates, milestone, and confidentiality
126. update_work_item - Update a work item. Can modify title, description, labels, assignees, weight, state, status, parent hierarchy, children, health status, start/due dates, milestone, confidentiality, linked items, and custom fields
127. convert_work_item_type - Convert a work item to a different type (e.g. issue to task, task to incident)
128. list_work_item_statuses - List available statuses for a work item type in a project. Requires GitLab Premium/Ultimate with configurable statuses
129. list_custom_field_definitions - List available custom field definitions for a work item type in a project. Returns field names, types, and IDs needed for setting custom fields via update_work_item
130. move_work_item - Move a work item (issue, task, etc.) to a different project. Uses GitLab GraphQL issueMove mutation
131. list_work_item_notes - List notes and discussions on a work item. Returns threaded discussions with author, body, timestamps, and system/internal flags
132. create_work_item_note - Add a note/comment to a work item. Supports Markdown, internal notes, and threaded replies
133. get_timeline_events - List timeline events for an incident. Returns chronological events with notes, timestamps, and tags
134. create_timeline_event - Create a timeline event on an incident. Supports tags: 'Start time', 'End time', 'Impact detected', 'Response initiated', 'Impact mitigated', 'Cause identified'
135. list_webhooks - List all configured webhooks for a GitLab project or group. Provide either project_id or group_id
136. list_webhook_events - List recent webhook events (past 7 days) for a project or group webhook. Use summary mode for overview, then get_webhook_event for full details
137. get_webhook_event - Get full details of a specific webhook event by ID, including request/response payloads
138. search_code - Search for code across all projects on the GitLab instance (requires advanced search or exact code search to be enabled)
139. search_project_code - Search for code within a specific GitLab project (requires advanced search or exact code search to be enabled)
140. search_group_code - Search for code within a specific GitLab group (requires advanced search or exact code search to be enabled)
141. execute_graphql - Execute a GitLab GraphQL query

Testing 🧪

The project includes comprehensive test coverage including remote authorization:

# 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.