GitLab MCP server

gitlab-mcp

A production-ready MCP server for GitLab. It lets AI assistants read and manage GitLab projects, merge requests, issues, pipelines, wikis, releases, and more through a broad, policy-controlled tool registry.

Highlights

• Comprehensive GitLab coverage — projects, merge requests (with code-context analysis and rebase), issues, pipelines (schedules, triggers, test reports, waits, log search), environments and deployments, wikis, milestones and iterations, releases, protected branches and tags, snippets, webhooks, vulnerabilities, labels, commits, GraphQL, and file management
• Multiple transports — stdio for local CLI usage, Streamable HTTP for remote deployments, optional SSE
• Flexible authentication — personal access tokens, OAuth 2.0 PKCE, external token scripts, token files, cookie-based auth, and per-request remote authorization
• Policy engine — readonly/modify/full modes, tool allowlist/denylist, feature toggles, and project-scoped restrictions
• Enterprise networking — HTTP/HTTPS proxy, custom CA certificates, Cloudflare bypass, multi-instance API rotation
• Output control — JSON, compact JSON, or YAML formatting with configurable response size limits, optional JMESPath projection, and an optional masking policy for tokens, IPs, and keywords
• Agent guidance — initialize instructions, workflow prompts (review an MR, triage a pipeline failure or vulnerabilities), and recovery hints on errors

Usage

Supported clients

Claude Desktop, Claude Code, VS Code, GitHub Copilot Chat (VS Code), Cursor, JetBrains AI Assistant, GitLab Duo, and any MCP client that supports stdio or streamable HTTP.

Current client format references:

• MCP transports and protocol
• Claude Code MCP
• VS Code MCP servers
• Cursor MCP
• JetBrains AI Assistant MCP

Authentication methods

The server supports three auth patterns:

1. Personal Access Token (PAT)
2. OAuth 2.0 PKCE (recommended for local interactive use)
3. Remote per-request auth (REMOTE_AUTHORIZATION=true, HTTP mode)

OAuth2 setup (stdio, recommended for local interactive use)

1. Create a GitLab OAuth application in Settings -> Applications.
2. Set redirect URI to http://127.0.0.1:8765/callback (or your custom callback).
3. Set scope to api.
4. Copy the Application ID as GITLAB_OAUTH_CLIENT_ID.

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "gitlab-mcp@latest"],
      "env": {
        "GITLAB_USE_OAUTH": "true",
        "GITLAB_OAUTH_CLIENT_ID": "your_oauth_client_id",
        "GITLAB_OAUTH_REDIRECT_URI": "http://127.0.0.1:8765/callback",
        "GITLAB_API_URL": "https://gitlab.com/api/v4",
        "GITLAB_ALLOWED_PROJECT_IDS": "",
        "GITLAB_PERMISSION_MODE": "full",
        "USE_GITLAB_WIKI": "true",
        "USE_MILESTONE": "true",
        "USE_PIPELINE": "true"
      }
    }
  }
}

If your OAuth app is confidential, also set GITLAB_OAUTH_CLIENT_SECRET.

Personal Access Token setup (stdio)

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "gitlab-mcp@latest"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
        "GITLAB_API_URL": "https://gitlab.com/api/v4",
        "GITLAB_ALLOWED_PROJECT_IDS": "",
        "GITLAB_PERMISSION_MODE": "full",
        "USE_GITLAB_WIKI": "true",
        "USE_MILESTONE": "true",
        "USE_PIPELINE": "true"
      }
    }
  }
}

VS Code .vscode/mcp.json examples

PAT with secure prompt input:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "gitlab_token",
      "description": "GitLab Personal Access Token",
      "password": true
    }
  ],
  "servers": {
    "gitlab": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/gitlab-mcp/dist/index.js"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "${input:gitlab_token}",
        "GITLAB_API_URL": "https://gitlab.com/api/v4",
        "GITLAB_PERMISSION_MODE": "full"
      }
    }
  }
}

OAuth (confidential app) with secure prompt input:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "gitlab_oauth_secret",
      "description": "GitLab OAuth Client Secret",
      "password": true
    }
  ],
  "servers": {
    "gitlab": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/gitlab-mcp/dist/index.js"],
      "env": {
        "GITLAB_USE_OAUTH": "true",
        "GITLAB_OAUTH_CLIENT_ID": "your_oauth_client_id",
        "GITLAB_OAUTH_CLIENT_SECRET": "${input:gitlab_oauth_secret}",
        "GITLAB_OAUTH_REDIRECT_URI": "http://127.0.0.1:8765/callback",
        "GITLAB_API_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}

GitHub Copilot Chat in VS Code uses the same .vscode/mcp.json format.

Claude Desktop / Claude Code / Cursor

Claude Desktop reads claude_desktop_config.json. Claude Code supports project-level .mcp.json and claude mcp add-json. Cursor uses .cursor/mcp.json.

{
  "mcpServers": {
    "gitlab": {
      "command": "node",
      "args": ["/absolute/path/to/gitlab-mcp/dist/index.js"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
        "GITLAB_API_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}

GitLab Duo (~/.gitlab/duo/mcp.json)

{
  "mcpServers": {
    "gitlab": {
      "command": "node",
      "args": ["/absolute/path/to/gitlab-mcp/dist/index.js"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
        "GITLAB_API_URL": "https://gitlab.com/api/v4"
      }
    }
  },
  "approvedTools": ["gitlab_get_project", "gitlab_list_merge_requests"]
}

JetBrains AI Assistant

JetBrains can import an existing MCP JSON config or register the server manually. Use stdio command node /absolute/path/to/gitlab-mcp/dist/index.js, or HTTP endpoint http://127.0.0.1:3333/mcp with required headers.

Remote authorization (multi-user HTTP)

Start server:

REMOTE_AUTHORIZATION=true \
HTTP_HOST=0.0.0.0 \
MCP_ALLOWED_HOSTS=127.0.0.1 \
HTTP_PORT=3333 \
node dist/http.js

Client config:

{
  "mcpServers": {
    "gitlab": {
      "url": "http://127.0.0.1:3333/mcp",
      "headers": {
        "Authorization": "Bearer glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Dynamic per-request API URL:

REMOTE_AUTHORIZATION=true \
ENABLE_DYNAMIC_API_URL=true \
HTTP_HOST=0.0.0.0 \
MCP_ALLOWED_HOSTS=127.0.0.1 \
HTTP_PORT=3333 \
node dist/http.js

Add header in client requests:

{
  "headers": {
    "Authorization": "Bearer glpat-xxxxxxxxxxxxxxxxxxxx",
    "X-GitLab-API-URL": "https://gitlab.example.com/api/v4"
  }
}

Remote auth behavior matrix:

Server Mode	Required Request Headers	Token Fallback Chain
REMOTE_AUTHORIZATION=false on local HTTP bind only	none	enabled
REMOTE_AUTHORIZATION=true	Authorization: Bearer <token>, Private-Token: <token>, or Job-Token: <token>	disabled
REMOTE_AUTHORIZATION=true + ENABLE_DYNAMIC_API_URL=true	Authorization, Private-Token, or Job-Token, and X-GitLab-API-URL: https://host/api/v4	disabled

When HTTP_HOST is not 127.0.0.1, localhost, or ::1, HTTP startup rejects server-side GITLAB_PERSONAL_ACCESS_TOKEN or GITLAB_JOB_TOKEN unless inbound requests are protected by MCP_HTTP_AUTH_TOKEN, REMOTE_AUTHORIZATION=true, or GITLAB_MCP_OAUTH=true.

Docker

For containerized deployments, PAT or remote auth is recommended. OAuth interactive callback flow is usually less convenient in containers. The Compose service listens on 0.0.0.0 inside the container but publishes only 127.0.0.1:3333 on the host by default. For the remote-authorization example, set REMOTE_AUTHORIZATION=true in .env, leave server-side GitLab credentials empty, and send each client's GitLab token as shown above.

docker compose up --build -d

or:

docker build -t gitlab-mcp .

docker run -d \
  --name gitlab-mcp \
  -p 127.0.0.1:3333:3333 \
  -e HTTP_HOST=0.0.0.0 \
  -e MCP_ALLOWED_HOSTS=127.0.0.1 \
  -e REMOTE_AUTHORIZATION=true \
  -e GITLAB_API_URL=https://gitlab.com/api/v4 \
  gitlab-mcp

Clients must send their GitLab credential in Authorization: Bearer <token>, Private-Token, or Job-Token. To keep a GitLab token in the container instead, set a separate 32+ character MCP_HTTP_AUTH_TOKEN and require clients to send that value as the bearer token; never expose a server-held GitLab token as the MCP bearer.

Compatibility notes

• GITLAB_PROJECT_ID is not a supported environment variable in this repository.
• To set an effective default project, use GITLAB_ALLOWED_PROJECT_IDS with one project ID, or pass project_id in tool arguments.
• CLI argument overrides such as --token or --api-url are not implemented (--env-file is supported).
• JSON config files do not support comments (//).

MCP Server Configuration

HTTP server

pnpm install
cp .env.example .env
pnpm build

# stdio (local MCP)
pnpm start

# streamable HTTP server (http://127.0.0.1:3333/mcp)
pnpm start:http

# optional: load a specific env file
pnpm start -- --env-file .env.local
pnpm start:http -- --env-file .env.local

Transport and entrypoint

Transport	Entry Point	Endpoint	Best For
stdio	node dist/index.js	stdin/stdout	Local single-user MCP clients
Streamable HTTP	node dist/http.js	POST/GET/DELETE /mcp	Remote/shared deployments
SSE (legacy)	node dist/http.js	GET /sse, POST /messages	Legacy SSE-only clients (SSE=true)
Health	node dist/http.js	GET /healthz	Liveness/readiness checks

SSE=true is not compatible with REMOTE_AUTHORIZATION=true.

Tool Categories

Tools are organized into these categories. All GitLab tools use the gitlab_ prefix, except health_check.

Category	Examples
Projects	get_project, list_projects, create_repository, update_project
Repository	get_repository_tree, get_file_contents, push_files, protected branches
Merge Requests	list_merge_requests, get_merge_request_conflicts, merge_merge_request
MR Code Context	get_merge_request_code_context (advanced code review)
MR Discussions	list_merge_request_discussions, create_merge_request_thread
MR Notes	list_merge_request_notes, create_merge_request_note
Draft Notes	list_draft_notes, create_draft_note, bulk_publish_draft_notes
Issues	list_issues, create_issue, update_issue, issue links
Pipelines	list_pipelines, list_pipeline_schedules, get_pipeline_test_report, wait_for_pipeline
Deployments	create_environment, stop_environment, approve_deployment, list_deployment_merge_requests
Commits	list_commits, get_commit, get_commit_diff
Labels	list_labels, create_label, update_label
Milestones	list_milestones, list_group_milestones, create_group_iteration, burndown events
Snippets	list_project_snippets, create_project_snippet
Security	list_project_vulnerabilities, dismiss_vulnerability (Ultimate)
Webhooks	list_webhooks, create_webhook, list_webhook_events
Releases	list_releases, create_release, download_release_asset
Wiki	list_wiki_pages, create_wiki_page, update_wiki_page
Uploads	upload_markdown, download_attachment
GraphQL	execute_graphql_query, execute_graphql_mutation
Users & Groups	get_users, list_group_members, list_namespaces, list_events
Opt-in	api_request (raw REST), orbit_query (GitLab Orbit)
Health	health_check (optionally verifies GitLab connectivity and auth)

During initialize, the server also sends MCP instructions: a short briefing on ID formats, token-saving review and CI workflows, gitlab_discover_tools, untrusted content, and the active permission mode, project scope, and toolsets.

See docs/tools.md for usage details and docs/tools-index.md for the generated complete registry.

Policy & Security

The policy engine controls which tools are available at registration time:

# Read-only mode — exposes only read and GraphQL query capabilities
GITLAB_PERMISSION_MODE=readonly

# Modify mode — allows read/write/admin, but hides delete-capability tools
GITLAB_PERMISSION_MODE=modify

# Deprecated legacy kill switch; true takes precedence and forces readonly
GITLAB_READ_ONLY_MODE=true

# Disable specific capability classes without going fully read-only
GITLAB_DISABLED_CAPABILITIES=delete,graphql

# Only expose specific tools (supports with or without gitlab_ prefix)
GITLAB_ALLOWED_TOOLS=get_project,list_merge_requests,get_merge_request

# Or select compact domain presets (multiple values form a union)
GITLAB_TOOLSETS=core,wiki

# Opt in only for clients that still call legacy duplicate names
GITLAB_ENABLE_COMPATIBILITY_ALIASES=true

# Sensitive variable administration is hidden until explicitly enabled
GITLAB_ENABLE_CI_VARIABLE_TOOLS=true
# Optional second gate; callers must also pass include_value=true
GITLAB_ALLOW_CI_VARIABLE_VALUES=false

# Group Dependency Proxy administration is also opt-in
GITLAB_ENABLE_DEPENDENCY_PROXY_TOOLS=true

# Block tools by regex pattern
GITLAB_DENIED_TOOLS_REGEX=^gitlab_(delete|create)_

# Restrict to specific projects
GITLAB_ALLOWED_PROJECT_IDS=123,456,789

# Legacy compatibility setting; raw GraphQL remains disabled in project-scoped mode
GITLAB_ALLOW_GRAPHQL_WITH_PROJECT_SCOPE=false

# Disable feature groups
USE_PIPELINE=false
USE_GITLAB_WIKI=false

The two sensitive tool families use two independent gates. Enabling a family does not add it to the default core registry; select its toolset (or all) as well:

GITLAB_TOOLSETS=core,ci-variables,dependency-proxy
GITLAB_ENABLE_CI_VARIABLE_TOOLS=true
GITLAB_ENABLE_DEPENDENCY_PROXY_TOOLS=true

Unsafe or invalid GITLAB_DENIED_TOOLS_REGEX patterns fail startup.

In modify mode, raw GraphQL mutation tools remain available for updates, but the server parses each document and blocks mutation-root fields containing deletion or teardown verbs such as delete, destroy, remove, purge, erase, revoke, unprotect, or stop. Aliases and fragment expansion cannot bypass the check, and documents that cannot be verified fail closed.

GITLAB_ALLOWED_PROJECT_IDS is a strict resource boundary, not just a default project. Project-scoped tools validate every supplied source, target, and parent project ID. Safe global list/search tools return only allowed projects (global code search is executed once per allowed project), while group-wide, namespace-wide, user-wide, event-wide, fork, and unscoped create operations are hidden. Todo reads are filtered and a single todo is verified before mutation. Raw GraphQL executors are always hidden because an arbitrary document cannot be proven project-safe; project-bound Work Item tools remain available and enforce the same allowlist. The legacy GITLAB_ALLOW_GRAPHQL_WITH_PROJECT_SCOPE variable is retained for configuration compatibility but cannot override this boundary.