GitLab MCP Server







 

English | 한국어 | 简体中文

📖 [Documentation →](https://zereight.github.io/gitlab-mcp/) Setup guides, environment variables, and the full tool reference live on the hosted docs site.


@zereight/mcp-gitlab

Agent-workflow-optimized GitLab MCP — manage projects, merge requests, issues, pipelines, wiki, releases, tags, 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?

• **261 tools + discover_tools** — start with a small toolset; activate more at runtime without CQRS-style grouping
• MR 2-step review — list_merge_request_changed_files → batched get_merge_request_file_diff
• Agent Skill built in — workflow guidance in skills/gitlab-mcp/
• 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

How we compare

| | @zereight/mcp-gitlab | GitLab MCP A (community CQRS-style) |

|---|----------------------|-------------------------------------|

| Best for | AI agent workflows | Enterprise multi-instance / grouped tools |

| Tool model | ~261 granular tools + discover_tools | ~50–60 grouped browse_* / manage_* tools |

| MR review | 2-step batched diff | Varies |

| Node.js | >=18.17 | Often >=24 |

| License | MIT | Varies |

Full comparison →

Quick start: choose either Personal Access Token or OAuth2 setup below, install @zereight/mcp-gitlab, 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
• Stateless Mode — Multi-Pod HPA
• Custom Agents and Multiple PAT Setup

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
• OAuth without a localhost callback (SSO, remote shell, background clients): run zereight-mcp-gitlab auth (GitLab 17.9+ device flow; 17.2–17.8 need oauth2_device_grant_flow), then start the server with GITLAB_USE_OAUTH=true. See standalone device-flow command.

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.

Install the server once:

brew tap zereight/gitlab-mcp https://github.com/zereight/gitlab-mcp
brew install zereight/gitlab-mcp/zereight-mcp-gitlab

Or with npm:

npm install -g @zereight/mcp-gitlab

Or with Nix, by adding this flake to your own:

# flake.nix
inputs.gitlab-mcp.url = "github:zereight/gitlab-mcp";

# wherever you configure your MCP client:
command = lib.getExe inputs.gitlab-mcp.packages.${system}.default;

The store path is pinned by your lock file; update it with nix flake update gitlab-mcp.

The examples use zereight-mcp-gitlab, a less collision-prone alias for the legacy mcp-gitlab binary. If your MCP client cannot find it, use the absolute path from which zereight-mcp-gitlab.

No global install? Pin npx to the previous stable release (the version these docs recommend), for example npx -y @zereight/mcp-gitlab@2.1.60. If you always want the newest release, use npx -y @zereight/mcp-gitlab@latest instead. The server prints a notice to stderr on startup when a newer version is available (disable with GITLAB_DISABLE_VERSION_CHECK=true).

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": "zereight-mcp-gitlab",
      "args": ["--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, deprecated — prefer --permission-mode=readonly)
• --permission-mode - Permission level: readonly, modify (no delete tools), or full (replaces GITLAB_PERMISSION_MODE, default full)
• --use-wiki=true - Enable wiki API (replaces USE_GITLAB_WIKI, legacy — prefer GITLAB_TOOLSETS=wiki)
• --use-milestone=true - Enable milestone API (replaces USE_MILESTONE, legacy — prefer GITLAB_TOOLSETS=milestones)
• --use-pipeline=true - Enable pipeline API (replaces USE_PIPELINE, legacy — prefer GITLAB_TOOLSETS=pipelines)
• --disable-version-check=true - Disable the startup new-version notice (replaces GITLAB_DISABLE_VERSION_CHECK)

CLI arguments take precedence over environment variables.

zereight-mcp-gitlab auth is a subcommand (not an MCP server flag). It runs GitLab device flow and exits. See CLI Arguments.

Fine-grained tool filtering: use GITLAB_PERMISSION_MODE=modify to allow create/update while

blocking every delete tool (including delete mutations through execute_graphql and

push_files delete/move actions), or

GITLAB_PERMISSION_MODE=readonly for read-only access. You can also

enable toolset groups with GITLAB_TOOLSETS=<group,…>, allow-list individual tools with

GITLAB_TOOLS=<tool,…> (e.g. read-only groups plus a few specific write tools), and

deny-list by pattern with GITLAB_DENIED_TOOLS_REGEX. The legacy USE_GITLAB_WIKI /

USE_MILESTONE / USE_PIPELINE flags are kept for backward compatibility only.

See Tools Reference and

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_PERMISSION_MODE=readonly \
  -e GITLAB_TOOLSETS=wiki,milestones,pipelines \
  -e SSE=true \
  -e SSE_AUTH_TOKEN=your_mcp_sse_token \
  -p 3333:3002 \
  zereight050/gitlab-mcp

{
  "mcpServers": {
    "gitlab": {
      "type": "sse",
      "url": "http://localhost:3333/sse",
      "headers": {
        "Authorization": "Bearer your_mcp_sse_token"
      }
    }
  }
}

• streamable-http

docker run -i --rm \
  -e HOST=0.0.0.0 \
  -e REMOTE_AUTHORIZATION=true \
  -e GITLAB_API_URL="https://gitlab.com/api/v4" \
  -e GITLAB_PERMISSION_MODE=readonly \
  -e GITLAB_TOOLSETS=wiki,milestones,pipelines \
  -e STREAMABLE_HTTP=true \
  -p 3333:3002 \
  zereight050/gitlab-mcp

{
  "mcpServers": {
    "gitlab": {
      "type": "streamable-http",
      "url": "http://localhost:3333/mcp",
      "headers": {
        "Authorization": "Bearer glpat-..."
      }
    }
  }
}

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.

Remote MCP clients such as OpenCode, MCPJam, and Claude.ai can send their own

callback URL during authorization. If you cannot register every client callback

URL in GitLab, enable GITLAB_OAUTH_CALLBACK_PROXY=true. With callback proxy

mode, GitLab only needs one registered redirect URI: {MCP_SERVER_URL}/callback.

GITLAB_OAUTH_REDIRECT_URI is for local OAuth (GITLAB_USE_OAUTH) only. It does

not override remote MCP OAuth client callback URLs and should not be used to fix

remote Unregistered redirect_uri errors.

This variable exists because the local OAuth flow starts a browser on the same

machine as the MCP server and listens for the callback on a local HTTP server,

for example http://127.0.0.1:8888/callback.

Remote MCP OAuth is different. In GITLAB_MCP_OAUTH=true mode, the MCP client

provides its own callback URL during /authorize. GITLAB_OAUTH_REDIRECT_URI

does not replace that client-provided URL.

| Mode | Enable with | Callback variable | GitLab redirect URI |

| ---------------- | ----------------------- | ---------------------------------- | ------------------------------------------------------- |

| Local OAuth | GITLAB_USE_OAUTH=true | GITLAB_OAUTH_REDIRECT_URI | http://127.0.0.1:8888/callback or your local callback |

| Remote MCP OAuth | GITLAB_MCP_OAUTH=true | GITLAB_OAUTH_CALLBACK_PROXY=true | {MCP_SERVER_URL}/callback |

Use GITLAB_OAUTH_REDIRECT_URI only when the MCP server itself owns the local

browser callback. Use GITLAB_OAUTH_CALLBACK_PROXY=true when a remote MCP client

owns the callback URL.

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

| Environment Variable | Required | Description |

| ----------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |

| GITLAB_MCP_OAUTH | ✅ | Set to true to enable |

| GITLAB_API_URL | ✅ | GitLab API base URL |

| GITLAB_OAUTH_APP_ID | ✅ | GitLab OAuth Application ID |

| MCP_SERVER_URL | ✅ | Public HTTPS URL of this MCP server |

| STREAMABLE_HTTP | ✅ | Must be true |

| GITLAB_OAUTH_CALLBACK_PROXY | optional | Set to true to use the MCP server's fixed /callback URL |

| GITLAB_OAUTH_SCOPES | optional | Comma-separated scopes (default: api,read_api,read_user) |

| GITLAB_OAUTH_ALLOWED_GROUPS | optional | Comma-separated group full paths — only members (and subgroup members) may obtain a token (replaces deprecated GITLAB_ALLOWED_GROUPS) |

When STREAMABLE_HTTP=true, server-side GitLab credentials (GITLAB_PERSONAL_ACCESS_TOKEN, GITLAB_JOB_TOKEN, GITLAB_AUTH_COOKIE_PATH, or GITLAB_USE_OAUTH) require REMOTE_AUTHORIZATION=true, GITLAB_MCP_OAUTH=true, or STREAMABLE_HTTP_AUTH_TOKEN.

**Troubleshooting Unregistered redirect_uri**

Check the redirect_uri in the browser URL. If it points to a client callback

such as http://127.0.0.1:xxxxx/.../callback, enable:

```env

GITLABOAUTHCALLBACK_PROXY=true

```

Do not fix remote MCP OAuth by changing GITLAB_OAUTH_REDIRECT_URI. That

variable is for local OAuth (GITLAB_USE_OAUTH) only.

docker run -i --rm \
  -e HOST=0.0.0.0 \
  -e GITLAB_MCP_OAUTH=true \
  -e GITLAB_OAUTH_CALLBACK_PROXY=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

| Environment Variable | Required | Description |

| --------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- |

| REMOTE_AUTHORIZATION | ✅ | Set to true to enable |

| STREAMABLE_HTTP | ✅ | Must be true |

| ENABLE_DYNAMIC_API_URL | optional | Allow per-request GitLab URL via X-GitLab-API-URL header |

| GITLAB_ALLOWED_HOSTS | optional | Comma-separated allowed X-GitLab-API-URL hosts; GITLAB_API_URL hosts are always allowed |

| GITLAB_ALLOW_UNAUTHENTICATED_TOOL_DISCOVERY | optional | Allow unauthenticated initialize, notifications/initialized, tools/list, and server/discover only (tool calls still require auth) |

| MCP_SERVER_URL / MCP_ALLOWED_HOSTS / MCP_ALLOWED_ORIGINS | optional | Allowed public /mcp host/origin values for DNS rebinding protection |

| MCP_TRUST_PROXY | optional | Trust Forwarded / X-Forwarded-* headers behind a reverse proxy (download URLs, Express req.ip, /mcp IP rate limits, OAuth rate limits) |

GITLAB_ALLOW_UNAUTHENTICATED_TOOL_DISCOVERY=true is intended for MCP gateways

or admin UIs that need to inspect tool metadata before a user provides a GitLab

token. Leave it disabled unless the tool list is safe to expose in your deployment.

When MCP_SERVER_URL is not set, remote download URLs fall back to the local

server address. Set MCP_TRUST_PROXY=true only if the server is reachable through a

trusted reverse proxy and direct client access to the MCP server is blocked.

This enables Express trust proxy for Streamable HTTP and SSE, derives public

download URLs from Forwarded / X-Forwarded-Proto / X-Forwarded-Host /

X-Forwarded-Prefix, and keeps OAuth endpoint rate limiting working when

proxies send X-Forwarded-For with a client port (for example 1.2.3.4:5678).

Existing OAuth+proxy deployments must set this explicitly after the flag was

introduced.

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 (or GITLAB_MCP_OAUTH=true), MCP_TRUST_PROXY=true (behind a reverse proxy), MAX_REQUESTS_PER_MINUTE=300, MCP_SERVER_URL or MCP_ALLOWED_HOSTS, HOST, PORT
• Multiple side-by-side deployments: set a distinct MCP_SERVER_NAME per instance (e.g. gitlab-selfhosted-readonly) so clients, logs, and telemetry can tell them apart
• Multi-pod HPA (stateless): above + OAUTH_STATELESS_MODE=true, OAUTH_STATELESS_SECRET (same across all pods). See Stateless Mode.

Commonly referenced variables:

• GITLAB_API_URL
• GITLAB_PERSONAL_ACCESS_TOKEN
• GITLAB_USE_OAUTH
• REMOTE_AUTHORIZATION
• MCP_TRUST_PROXY
• MAX_REQUESTS_PER_MINUTE
• MAX_SESSIONS
• MCP_ALLOWED_HOSTS
• MCP_ALLOWED_ORIGINS
• GITLAB_MCP_OAUTH
• GITLAB_OAUTH_CALLBACK_PROXY
• OAUTH_REGISTER_RATE_LIMIT_PER_HOUR
• OAUTH_STATELESS_MODE
• OAUTH_STATELESS_SECRET

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

For callback proxy mode details, see GitLab MCP OAuth Callback Proxy.

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_PERMISSION_MODE=readonly \
  -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: /mcp requests are limited to MAX_REQUESTS_PER_MINUTE per client IP, and per MCP session when using OAuth or remote authorization (default 60). See environment-variables.md.
• 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)

1. 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:

| Variable | Required | Description |

| ------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

| GITLAB_MCP_OAUTH | Yes | Set to true to enable |

| GITLAB_OAUTH_APP_ID | Yes | Client ID of the pre-registered GitLab OAuth application |

| MCP_SERVER_URL | Yes | Public HTTPS URL of your MCP server; also allowed for /mcp Host/Origin checks |

| GITLAB_API_URL | Yes | Your GitLab instance API URL (e.g. https://gitlab.com/api/v4) |

| STREAMABLE_HTTP | Yes | Must be true (SSE is not supported) |

| GITLAB_OAUTH_SCOPES | No | Comma-separated GitLab scopes to request (e.g. api,read_user). Defaults to api (or read_api when GITLAB_READ_ONLY_MODE=true). The pre-registered application must be configured with at least these scopes. |

| OAUTH_REGISTER_RATE_LIMIT_PER_HOUR | No | Per-IP rolling limit for Dynamic Client Registration (POST /register). Default 20/hour; range 1–1000. Raise when clients (e.g. multiple IDE windows) hit registration throttling. Not a GitLab API limit. |

| MCP_DANGEROUSLY_ALLOW_INSECURE_ISSUER_URL | No | Set true for local HTTP dev only |

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)

• DCR rate limiting: POST /register is limited to OAUTH_REGISTER_RATE_LIMIT_PER_HOUR

per client IP (default 20/hour). Separate from /mcp limits and GitLab API quotas.

See environment-variables.md.

• 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](./skills/gitlab-mcp/SKILL.md) — Core guide (~800 tokens) with toolset overview, key workflows, and parameter hints
• [reference/](./skills/gitlab-mcp/reference/) — Detailed workflow docs for code review, merge requests, issues, pipelines, and vulnerability triage

Install with the skills CLI:

npx skills add zereight/gitlab-mcp --skill gitlab-mcp-skill

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

Tools 🛠️

<details>

<summary>Click to expand</summary>

<!-- TOOLS-START -->

1. merge_merge_request - Merge a merge request
2. approve_merge_request - Approve a merge request
3. unapprove_merge_request - Unapprove a merge request
4. get_merge_request_approval_state - Get merge request approval details including approvers
5. get_merge_request_conflicts - Get the conflicts of a merge request
6. list_merge_request_pipelines - List pipelines for a merge request with pagination
7. execute_graphql - Execute a GitLab GraphQL query
8. create_or_update_file - Create or update a file in a GitLab project
9. search_repositories - Search for GitLab projects
10. create_repository - Create a new GitLab project
11. create_group - Create new group or subgroup
12. get_file_contents - Get contents of a file or directory from a GitLab project
13. push_files - Push multiple files in a single commit
14. create_issue - Create a new issue
15. create_merge_request - Create a new merge request
16. fork_repository - Fork a project to your account or specified namespace
17. create_branch - Create a new branch
18. get_branch - Get branch details (commit, protection status)
19. list_branches - List branches in project with search filter
20. delete_branch - Delete branch from project
21. list_protected_branches - List protected branches in a project, supports search filter
22. get_protected_branch - Get details of a single protected branch (access levels, force push settings)
23. protect_branch - Protect a repository branch (set push/merge/unprotect access levels)
24. unprotect_branch - Remove protection from a previously protected branch
25. update_default_branch - Change the default branch of a project
26. get_merge_request - Get details of a merge request (mergeRequestIid or branchName required). Set include_summaries=true for deployment/commit/approval summaries
27. get_merge_request_diffs - Get the changes/diffs of a merge request (mergeRequestIid or branchName required)
28. list_merge_request_changed_files - List changed file paths in a merge request without diff content (mergeRequestIid or branchName required)
29. list_merge_request_diffs - List merge request diffs with pagination (mergeRequestIid or branchName required)
30. get_merge_request_file_diff - Get diffs for specific files from a merge request (mergeRequestIid or branchName required)
31. list_merge_request_versions - List all versions of a merge request
32. get_merge_request_version - Get a specific version of a merge request
33. get_branch_diffs - Get diffs between two branches or commits
34. update_merge_request - Update a merge request (mergeRequestIid or branchName required)
35. create_note - Create a new note (comment) to an issue or merge request
36. create_merge_request_thread - Create a new thread on a merge request
37. resolve_merge_request_thread - Resolve a thread on a merge request
38. mr_discussions - List discussion items for a merge request
39. delete_merge_request_discussion_note - Delete a discussion note on a merge request
40. update_merge_request_discussion_note - Update a discussion note on a merge request
41. create_merge_request_discussion_note - Add a new discussion note to an existing merge request thread
42. create_merge_request_note - Add a new note to a merge request
43. delete_merge_request_note - Delete an existing merge request note
44. get_merge_request_note - Get a specific note for a merge request
45. get_merge_request_notes - List notes for a merge request
46. update_merge_request_note - Modify an existing merge request note
47. get_draft_note - Get a single draft note from a merge request
48. list_draft_notes - List draft notes for a merge request
49. create_draft_note - Create a draft note for a merge request
50. update_draft_note - Update an existing draft note
51. delete_draft_note - Delete a draft note
52. publish_draft_note - Publish a single draft note
53. bulk_publish_draft_notes - Publish all draft notes for a merge request. Optionally sets reviewerstate and posts a summary note (GitLab 19.2+). Can set reviewerstate even with no drafts.
54. list_merge_request_emoji_reactions - List all emoji reactions on a merge request
55. list_merge_request_note_emoji_reactions - List all emoji reactions on a merge request note. Pass discussion_id for discussion thread replies.
56. create_merge_request_emoji_reaction - Add an emoji reaction to a merge request (e.g. thumbsup, rocket, eyes)
57. delete_merge_request_emoji_reaction - Remove an emoji reaction from a merge request
58. create_merge_request_note_emoji_reaction - Add an emoji reaction to a merge request note. Pass discussion_id for discussion thread replies.
59. delete_merge_request_note_emoji_reaction - Remove an emoji reaction from a merge request note. Pass discussion_id for discussion thread replies.
60. update_issue_note - Modify an existing issue thread note
61. create_issue_note - Add a note to an issue, optionally replying to a discussion thread
62. list_issue_emoji_reactions - List all emoji reactions on an issue
63. list_issue_note_emoji_reactions - List all emoji reactions on an issue note. Pass discussion_id for discussion thread replies.
64. create_issue_emoji_reaction - Add an emoji reaction to an issue (e.g. thumbsup, rocket, eyes)
65. delete_issue_emoji_reaction - Remove an emoji reaction from an issue
66. create_issue_note_emoji_reaction - Add an emoji reaction to an issue note. Pass discussion_id for discussion thread replies.
67. delete_issue_note_emoji_reaction - Remove an emoji reaction from an issue note. Pass discussion_id for discussion thread replies.
68. list_issues - List issues (default: created by current user; use scope='all' for all)
69. my_issues - List issues assigned to the authenticated user
70. get_issue - Get details of a specific issue. Returns a slim milestone by default; set full_response=true for the complete milestone object
71. update_issue - Update an issue. Returns a slim confirmation by default; set full_response=true for the complete updated issue object
72. update_issue_description_patch - Apply a patch (search/replace or unified diff) to an issue description. Reduces token usage by allowing small changes without sending the full description. Supports dryrun to preview changes and createnote to summarize updates.
73. delete_issue - Delete an issue
74. list_todos - List GitLab to-do items for the current user
75. mark_todo_done - Mark a GitLab to-do item as done
76. mark_all_todos_done - Mark all pending GitLab to-do items as done for the current user
77. list_issue_links - List all issue links for a specific issue
78. list_issue_discussions - List discussions for an issue
79. get_issue_link - Get a specific issue link
80. create_issue_link - Create an issue link between two issues
81. delete_issue_link - Delete an issue link
82. list_namespaces - List all namespaces (users and groups) available to the current user. Filter by kind='group' for groups only.
83. get_namespace - Get details of a namespace (user or group) by ID or path. Groups are namespaces with kind='group'.
84. verify_namespace - Verify if a namespace path exists. Use parent_id to scope the check to a specific parent namespace — required for nested namespaces where the same path may exist under different parents.
85. get_project - Get details of a specific project
86. list_projects - List projects accessible by the current user
87. update_project - Update project settings such as description, visibility, default branch, and feature access levels
88. list_project_members - List members of a GitLab project
89. list_group_members - List members of a GitLab group with optional name or username search
90. list_labels - List labels for a project
91. get_label - Get a single label from a project
92. create_label - Create a new label in a project
93. update_label - Update an existing label in a project
94. delete_label - Delete a label from a project
95. list_group_projects - List projects in a group
96. list_wiki_pages - List wiki pages in a project
97. get_wiki_page - Get details of a specific wiki page
98. create_wiki_page - Create a wiki page in a project
99. update_wiki_page - Update a wiki page in a project
100. delete_wiki_page - Delete a wiki page from a project
101. list_group_wiki_pages - List wiki pages in a group
102. get_group_wiki_page - Get details of a specific group wiki page
103. create_group_wiki_page - Create a wiki page in a group
104. update_group_wiki_page - Update a wiki page in a group
105. delete_group_wiki_page - Delete a wiki page from a group
106. get_repository_tree - List files and directories in a repository
107. list_pipelines - List pipelines with filtering options
108. get_pipeline - Get details of a specific pipeline
109. get_pipeline_variables - Get variables configured for a pipeline
110. get_pipeline_test_report - Get pipeline test report
111. get_pipeline_test_report_summary - Get pipeline test report summary
112. delete_pipeline - Delete a pipeline. Requires the project Owner role, cannot be undone, and does not automatically delete child pipelines.
113. update_pipeline_metadata - Update pipeline metadata
114. list_deployments - List deployments with filtering options
115. get_deployment - Get deployment details, including approvalsummary, approvals, and pendingapproval_count when GitLab provides them
116. create_deployment - Create a deployment
117. update_deployment - Update a deployment status
118. delete_deployment - Delete a deployment
119. list_deployment_merge_requests - List merge requests shipped with a deployment
120. approve_deployment - Approve or reject a protected-environment deployment
121. list_environments - List environments in a project
122. get_environment - Get details of a specific environment
123. update_environment - Update an environment
124. delete_environment - Delete a stopped environment
125. stop_environment - Stop an environment
126. stop_stale_environments - Stop eligible stale environments; protected environments are excluded and environments are stopped, not deleted
127. delete_review_app_environments - Schedule deletion of stopped review-app environments one week later; dryrun defaults to true and actual scheduling requires dryrun=false
128. list_pipeline_triggers - List project pipeline trigger tokens
129. get_pipeline_trigger - Get a project pipeline trigger
130. create_pipeline_trigger - Create a project pipeline trigger
131. update_pipeline_trigger - Update a project pipeline trigger
132. delete_pipeline_trigger - Delete a project pipeline trigger
133. trigger_pipeline - Trigger a pipeline with a pipeline trigger token
134. list_pipeline_jobs - List all jobs in a specific pipeline
135. list_pipeline_trigger_jobs - List trigger jobs (bridges) in a pipeline
136. get_pipeline_job - Get details of a GitLab pipeline job number
137. get_pipeline_job_output - Get the output/trace of a pipeline job with optional pagination
138. validate_ci_lint - Validate provided GitLab CI/CD YAML content for a project
139. validate_project_ci_lint - Validate an existing .gitlab-ci.yml configuration for a project
140. list_ci_catalog_resources - List GitLab CI/CD Catalog resources/components visible to the user
141. get_ci_catalog_resource - Get details for a GitLab CI/CD Catalog resource, including versions and components
142. create_pipeline - Create a new pipeline for a branch or tag
143. retry_pipeline - Retry a failed or canceled pipeline
144. cancel_pipeline - Cancel a running pipeline
145. list_pipeline_schedules - List pipeline schedules in a project, optionally filtered to active or inactive
146. get_pipeline_schedule - Get details of a specific pipeline schedule, including its variables and last pipeline
147. list_pipeline_schedule_pipelines - List the pipelines that a pipeline schedule has triggered
148. create_pipeline_schedule - Create a new pipeline schedule for a branch or tag
149. update_pipeline_schedule - Update an existing pipeline schedule
150. delete_pipeline_schedule - Delete a pipeline schedule
151. play_pipeline_schedule - Run a pipeline schedule immediately
152. take_ownership_pipeline_schedule - Take ownership of a pipeline schedule
153. get_pipeline_schedule_variable - Get a single variable of a pipeline schedule
154. create_pipeline_schedule_variable - Create a variable for a pipeline schedule
155. update_pipeline_schedule_variable - Update a variable of a pipeline schedule
156. delete_pipeline_schedule_variable - Delete a variable from a pipeline schedule
157. play_pipeline_job - Run a manual pipeline job
158. play_pipeline_jobs - Play multiple manual pipeline jobs sequentially
159. retry_pipeline_job - Retry a failed or canceled pipeline job
160. cancel_pipeline_job - Cancel a running pipeline job
161. erase_pipeline_job - Erase a pipeline job log and artifacts
162. wait_for_pipeline - Wait for a pipeline to reach a terminal status
163. wait_for_job - Wait for a job to reach a terminal status
164. list_job_artifacts - List artifact files in a job's archive
165. download_job_artifacts - Download job artifact archive (zip) and save to a local path
166. get_job_artifact_file - Get content of a single file from a job's artifacts
167. list_merge_requests - List merge requests (without projectid: user's MRs; with projectid: project MRs)
168. list_group_merge_requests - List merge requests across all projects of a group and its subgroups
169. list_milestones - List milestones with filtering options
170. get_milestone - Get details of a specific milestone
171. create_milestone - Create a new milestone
172. edit_milestone - Edit an existing milestone
173. delete_milestone - Delete a milestone
174. get_milestone_issue - Get issues associated with a specific milestone
175. get_milestone_merge_requests - Get merge requests associated with a specific milestone
176. promote_milestone - Promote a milestone to the next stage
177. get_milestone_burndown_events - Get burndown events for a specific milestone
178. list_group_milestones - List group milestones with filtering options
179. get_group_milestone - Get details of a specific group milestone
180. create_group_milestone - Create a new group milestone
181. edit_group_milestone - Edit an existing group milestone
182. delete_group_milestone - Delete a group milestone
183. get_group_milestone_issue - Get issues associated with a specific group milestone
184. get_group_milestone_merge_requests - Get merge requests associated with a specific group milestone
185. get_group_milestone_burndown_events - Get burndown events for a specific group milestone
186. get_users - Get GitLab user details by usernames
187. get_user - Get user details by ID
188. whoami - Get current authenticated user details
189. list_commits - List repository commits with filtering options
190. get_commit - Get details of a specific commit
191. get_commit_diff - Get changes/diffs of a specific commit
192. get_file_blame - Get git blame for a file at a given ref. Each entry maps a contiguous range of source lines to the commit that last changed them (id, author, authoreddate, message). Use rangestart/range_end to limit blame to specific lines.
193. list_commit_statuses - List statuses for a commit
194. create_commit_status - Create or update the status of a commit
195. list_group_iterations - List group iterations with filtering options
196. upload_markdown - Upload a file for use in markdown content
197. download_attachment - Download an uploaded file from a project (images returned as base64; use local_path to save to disk)
198. health_check - Verify server status and authentication. Always reports the MCP server version (mcpserverversion). When authenticated, also reports the GitLab instance version from GET /api/v4/version (version, revision, enterprise). Version lookup failures do not fail the health check — those fields are omitted.
199. list_events - List events for the authenticated user (before/after: YYYY-MM-DD)
200. get_project_events - List events for a project (before/after: YYYY-MM-DD)
201. list_releases - List all releases for a project
202. get_release - Get a release by tag name
203. create_release - Create a new release
204. update_release - Update an existing release
205. delete_release - Delete a release (does not delete the tag)
206. create_release_evidence - Create release evidence (Premium/Ultimate)
207. download_release_asset - Download a release asset file by direct asset path
208. list_tags - List repository tags for a project
209. get_tag - Get a repository tag by name
210. create_tag - Create a new repository tag
211. delete_tag - Delete a repository tag
212. get_tag_signature - Get the X.509 signature of a signed tag (404 if unsigned)
213. get_work_item - Get a work item with full details including status, hierarchy, type, and widgets
214. list_work_items - List work items with filters (type, state, search, assignees, labels)
215. create_work_item - Create a work item (issue, task, incident, epic, etc.) with full field support
216. update_work_item - Update a work item (title, description, labels, assignees, state, parent, custom fields, etc.)
217. convert_work_item_type - Convert a work item to a different type
218. list_work_item_statuses - List available statuses for a work item type (Premium/Ultimate)
219. list_custom_field_definitions - List custom field definitions for a work item type
220. move_work_item - Move a work item to a different project
221. list_work_item_notes - List notes and discussions on a work item
222. create_work_item_note - Add a note to a work item (supports Markdown, internal notes, threads)
223. list_work_item_emoji_reactions - List all emoji reactions on a work item
224. list_work_item_note_emoji_reactions - List all emoji reactions on a work item note (comment, thread, or thread reply)
225. create_work_item_emoji_reaction - Add an emoji reaction to a work item (e.g. thumbsup, rocket, eyes)
226. delete_work_item_emoji_reaction - Remove an emoji reaction from a work item
227. create_work_item_note_emoji_reaction - Add an emoji reaction to a work item note (comment, thread, or thread reply)
228. delete_work_item_note_emoji_reaction - Remove an emoji reaction from a work item note (comment, thread, or thread reply)
229. get_timeline_events - List timeline events for an incident
230. create_timeline_event - Create a timeline event on an incident
231. list_webhooks - List webhooks for a project or group
232. create_webhook - Create a webhook on a project or group
233. update_webhook - Update an existing project or group webhook
234. delete_webhook - Delete a project or group webhook
235. list_webhook_events - List recent webhook events (past 7 days)
236. get_webhook_event - Get full details of a specific webhook event
237. search_code - Search for code across all projects (requires advanced search or Zoekt)
238. search_project_code - Search for code within a specific project (requires advanced search or Zoekt)
239. search_group_code - Search for code within a specific group (requires advanced search or Zoekt)
240. list_project_variables - List CI/CD variables for a project
241. get_project_variable - Get a single CI/CD variable from a project
242. create_project_variable - Create a CI/CD variable for a project
243. update_project_variable - Update an existing CI/CD variable in a project
244. delete_project_variable - Delete a CI/CD variable from a project
245. list_group_variables - List CI/CD variables for a group
246. get_group_variable - Get a single CI/CD variable from a group
247. create_group_variable - Create a CI/CD variable for a group
248. update_group_variable - Update an existing CI/CD variable in a group
249. delete_group_variable - Delete a CI/CD variable from a group
250. get_dependency_proxy_settings - Get dependency proxy settings for a group
251. update_dependency_proxy_settings - Update dependency proxy settings for a group (enable/disable, credentials for authenticated Docker Hub pulls)
252. list_dependency_proxy_blobs - List cached dependency proxy blobs for a group
253. purge_dependency_proxy_cache - Schedule purge of all cached dependency proxy blobs for a group
254. list_project_vulnerabilities - List vulnerabilities for a project with optional state, severity, and report type filters (GraphQL-backed, cursor pagination)
255. get_vulnerability - Get full details of a specific vulnerability
256. dismiss_vulnerability - Dismiss a vulnerability with a reason (acceptablerisk, falsepositive, usedintests, mitigatingcontrol, notapplicable) and optional comment
257. confirm_vulnerability - Confirm a vulnerability as a real finding requiring remediation
258. orbit_query - Execute a GitLab Orbit graph query over the indexed SDLC knowledge graph
259. orbit_get_schema - Fetch the current GitLab Orbit graph schema (node and edge types)
260. orbit_get_status - Check GitLab Orbit indexing status for the enabled scope
261. orbit_list_tools - List the MCP tool definitions exposed by GitLab Orbit
262. discover_tools - Discover and activate additional tool categories for this session. Available categories: mergerequests, issues, repositories, branches, projects, labels, ci, groups, pipelines, milestones, wiki, releases, tags, users, workitems, webhooks, search, variables, dependencyproxy, vulnerabilities, orbit. Already-active categories are listed in the response.

<!-- TOOLS-END -->

</details>

Wiki page titles vs. slugs

GitLab derives a wiki page's slug (its URL, /-/wikis/<slug>) from the page title. Passing title to update_wiki_page / update_group_wiki_page therefore renames the page and changes its URL — for nested pages it can also move the page to a different path — which breaks existing links.

To change only the displayed title while keeping the URL stable, do not pass title. Instead, store the display title in the page content's YAML front matter and update the content:

---
title: My Custom Display Title
---

Page body…

GitLab keeps the slug/URL untouched and shows the front-matter title in the UI. Read it back with get_wiki_page using render_html: true, which populates the front_matter field — the plain title field always reflects the slug-derived value.

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.