
gitlab-mcp
MCP server for GitLab: 100+ tools for projects, MRs, issues, pipelines, wikis and more via the GitLab REST/GraphQL API
Install with your AI
Paste into Claude Code, Cursor, or any agent — it reads the repo and wires the tool into your project.
Install and set up gitlab-mcp (mcp-stdio project) into my current project. Found on https://claudeers.com/gitlab-mcp Repo: https://github.com/zereight/gitlab-mcp Homepage/docs: https://zereight.github.io/gitlab-mcp/ Detected install method: mcp-stdio → claude mcp add gitlab-mcp -- npx -y @zereight/mcp-gitlab Category: mcp-servers. Platforms: cli, api, desktop, web. Read the repo's README for exact setup and env vars, then install it and wire it into my project. Claudeers Health Verdict: active; community-verified: false. Confirm the source before running anything.
claude mcp add gitlab-mcp -- npx -y @zereight/mcp-gitlab
git clone https://github.com/zereight/gitlab-mcp
// compatibility
| Platforms | cli, api, desktop, web |
|---|---|
| Operating systems | — |
| AI compatibility | claude |
| License | MIT |
| Pricing | open-source |
| Language | TypeScript |
GitLab MCP Server
English | 한국어 | 简体中文 | Português (Brasil)
📖 Documentation → Setup guides, environment variables, and the full tool reference live on the hosted docs site.
Install @zereight/mcp-gitlab with the recommended local personal-access-token setup. These commands use the same arguments as the Claude Code and Codex guides.
Install the zereight-mcp-gitlab binary first with npm install -g @zereight/mcp-gitlab, or Homebrew brew tap zereight/gitlab-mcp https://github.com/zereight/gitlab-mcp and brew install zereight/gitlab-mcp/zereight-mcp-gitlab.
Read the token without echo, then export it. The shell history keeps the variable name.
read -rs GITLAB_PERSONAL_ACCESS_TOKEN && export GITLAB_PERSONAL_ACCESS_TOKEN
| Client | Install |
|---|---|
| Claude Code | claude mcp add gitlab --transport stdio --scope local --env GITLAB_PERSONAL_ACCESS_TOKEN="$GITLAB_PERSONAL_ACCESS_TOKEN" --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab |
| Codex | codex mcp add gitlab --env GITLAB_PERSONAL_ACCESS_TOKEN="$GITLAB_PERSONAL_ACCESS_TOKEN" --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab |
| Cursor | Cursor setup guide |
| VS Code | VS Code setup guide |
| JSON clients | JSON-based MCP clients setup guide |
@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?
- 276 tools: 274 in toolsets +
execute_graphql+discover_tools— start with a small toolset; activate more at runtime without CQRS-style grouping - MR 2-step review —
list_merge_request_changed_files→ batchedget_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
- JMESPath result filtering — optional
jmespathon tool calls (seetools/list) shrinks JSON results without changing GitLab API requests; when response masking is enabled, JMESPath runs on masked data.
How we compare
| @zereight/mcp-gitlab | GitLab MCP A (community CQRS-style) | GitLab official MCP server | |
|---|---|---|---|
| Best for | AI agent workflows | Enterprise multi-instance / grouped tools | Built into GitLab, no separate install |
| Tool model | 276 tools: 274 in toolsets + execute_graphql + discover_tools | ~50–60 grouped browse_* / manage_* tools | Toolsets chosen with an HTTP header |
| MR review | 2-step batched diff | Varies | get_merge_request with diffs |
| Node.js | >=18.17 | Often >=24 | Node.js 20+ for stdio via mcp-remote |
| License | MIT | Varies | Part of GitLab |
Full comparison with GitLab MCP A →
GitLab also ships an official MCP server.
- Free, Premium, and Ultimate. Moved from Premium to Free in GitLab 19.2. Generally available in GitLab 19.5.
- On GitLab.com, a top-level group Owner allows access to the MCP server. On GitLab Self-Managed and GitLab Dedicated, an administrator controls the instance setting. Default rules are on the official page.
- Remote clients use HTTP
https://<gitlab.example.com>/api/v4/mcpwith OAuth 2.0 dynamic client registration. - stdio goes through
mcp-remoteand needs Node.js 20 or later. - Toolsets use the
X-Gitlab-Enabled-Mcp-Server-Toolsetsheader. An optionalX-Gitlab-Mcp-Server-Tool-Name-Prefixheader keeps the first 32 characters of a tool-name prefix.
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):
- Personal Access Token (
GITLAB_PERSONAL_ACCESS_TOKENorGITLAB_PERSONAL_ACCESS_TOKEN_FILE) — simplest setup - OAuth2 — Local Browser (
GITLAB_USE_OAUTH) — recommended for better security
For server/remote deployments:
- OAuth2 — MCP Proxy (
GITLAB_MCP_OAUTH) — for remote MCP clients such as Claude.ai - 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 needoauth2_device_grant_flow), then start the server withGITLAB_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/[email protected]. 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).
Claude Desktop one-click install (MCP Bundle)
Every GitHub release after v2.3.1 ships a gitlab-mcp.mcpb MCP Bundle. Download the latest bundle and open it with Claude Desktop (or drag it into Settings → Extensions). Claude Desktop asks for your Personal Access Token (stored as a sensitive value) and lets you set GITLAB_API_URL, GITLAB_PERMISSION_MODE, GITLAB_TOOLSETS, and GITLAB_MASKING_ENABLED. No separate Node.js or npm install is needed.
To build the bundle from source, run npm run pack:mcpb (writes gitlab-mcp.mcpb).
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 (replacesGITLAB_PERSONAL_ACCESS_TOKEN)--api-url- GitLab API URL (replacesGITLAB_API_URL)--read-only=true- Deprecated (removed in next major (v3.0.0)); use--permission-mode=readonlyinstead (replacesGITLAB_READ_ONLY_MODE)--permission-mode- Permission level:readonly,modify(no delete or teardown tools), orfull(replacesGITLAB_PERMISSION_MODE, defaultfull)--toolsets=all- Enable named toolsets except the explicit-onlyapitoolset (replacesGITLAB_TOOLSETS; unset uses the leancoredefault).gitlab_api_requestneeds--toolsets=api--tools=list_issues- Add individual tools (replacesGITLAB_TOOLS)--use-wiki=true- Deprecated (removed in next major (v3.0.0)); use--toolsets=core,wikiinstead (replacesUSE_GITLAB_WIKI)--use-milestone=true- Deprecated (removed in next major (v3.0.0)); use--toolsets=core,milestonesinstead (replacesUSE_MILESTONE)--use-pipeline=true- Deprecated (removed in next major (v3.0.0)); use--toolsets=core,pipelinesand appendvalidate_ci_lint,validate_project_ci_lintto the existing--toolslist (or set--tools=validate_ci_lint,validate_project_ci_lintwhen that list is unset) (replacesUSE_PIPELINE)--disable-version-check=true- Disable the startup new-version notice (replacesGITLAB_DISABLE_VERSION_CHECK)--masking-enabled=true- Enable text-response masking (replacesGITLAB_MASKING_ENABLED)--masking-config- Path to a masking configuration file (replacesGITLAB_MASKING_CONFIG)--masking-policy-file- Path to a protected managed-policy file (replacesGITLAB_MASKING_POLICY_FILE)--masking-workspace-dir- Directory used to resolve masking files (replacesGITLAB_MASKING_WORKSPACE_DIR)--download-dir- Directorydownload_attachmentsaves files under (replacesGITLAB_DOWNLOAD_DIR; default.gitlab-mcp-downloads)--compact-results=true- Truncate oversized MCP tool replies and attach a CLI command for the full payload (replacesGITLAB_MCP_COMPACT_RESULTS; default off)--compact-result-chars- Character threshold for compacting (replacesGITLAB_MCP_COMPACT_RESULT_CHARS; default4000)--compact-tools- Comma-separated tool names to compact when oversized, without turning global compact on (replacesGITLAB_MCP_COMPACT_TOOLS)--tool-profile-full(default) orslim.slimdrops draft notes, emoji reactions, labels, CI catalog tools, andcreate_groupfrom the initial list. Ignored whenGITLAB_TOOLSETSis set (replacesGITLAB_TOOL_PROFILE)
If you already set GITLAB_TOOLSETS or --toolsets, append wiki, milestones, or pipelines to that list instead of replacing it. If you already set GITLAB_TOOLS or --tools, append validate_ci_lint and validate_project_ci_lint to that list instead of replacing it. An explicit list replaces the default core toolset; it does not merge.
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.
The same binary is also a gh-style GitLab CLI (tool <name> or curated forms such as mr list). No MCP registration is needed — set a PAT, or run auth and set GITLAB_USE_OAUTH=true: see CLI without MCP. Use it for the full payload in a terminal. MCP replies stay in the chat unless you set GITLAB_MCP_COMPACT_RESULTS=true (or --compact-results), which replaces oversized tool replies with a preview and a CLI command. Human CLI is never compacted. Same permission mode, toolsets, denied-tools regex, and tool-policy filters. Destructive tools and GITLAB_TOOL_POLICY_APPROVE tools need --yes. See Human CLI.
Fine-grained tool filtering: use
GITLAB_PERMISSION_MODE=modifyto allow create/update while blocking every delete tool and the destructive teardown tools (cancel_pipeline,cancel_pipeline_job,stop_environment,stop_stale_environments,unprotect_branch,unprotect_tag) — including destructive mutations (deletion and teardown verbs) throughexecute_graphqlandpush_filesdelete/moveactions — orGITLAB_PERMISSION_MODE=readonlyfor read-only access. You can also enable toolset groups withGITLAB_TOOLSETS=<group,…>, allow-list individual tools withGITLAB_TOOLS=<tool,…>(e.g. read-only groups plus a few specific write tools), and deny-list by pattern withGITLAB_DENIED_TOOLS_REGEX. The legacyUSE_GITLAB_WIKI/USE_MILESTONE/USE_PIPELINEflags are deprecated (removed in next major (v3.0.0)). UseGITLAB_TOOLSETS=core,wiki,core,milestones, orcore,pipelines(USE_PIPELINEalso needsvalidate_ci_lint,validate_project_ci_lintappended to an existingGITLAB_TOOLSlist instead of replacing it). If you already setGITLAB_TOOLSETS, append the toolset to your existing list instead of replacing it. IfGITLAB_TOOLSis unset, setGITLAB_TOOLS=validate_ci_lint,validate_project_ci_lint. If it is already set, appendvalidate_ci_lint,validate_project_ci_lintinstead of replacing that list. See Tools Reference and Environment Variables.
[!CAUTION]
gitlab_api_request(toolsetapi) bypassesGITLAB_ALLOWED_GROUPSand other group restrictions, project allowlists, tool-level restrictions (GITLAB_TOOLS,GITLAB_DENIED_TOOLS_REGEXon other tools), and individual tool safety checks. The full token permission scope is exposed. Prompt injection can drive this tool. Operators who rely on these restrictions must NOT enable it. Enable it only by listingapiinGITLAB_TOOLSETS(GITLAB_TOOLSETS=all,discover_tools,GITLAB_TOOLS, legacyUSE_*flags, andGITLAB_TOOL_PROFILEdo not).GITLAB_ALLOWED_PROJECT_IDSis checked only for/projects/:idpaths. Endpoints such as/search,/users,/groups/:id, and/runnersare not constrained.GITLAB_PROJECT_IDand OAuth group allowlists are not enforced.
- sse
Pass the variable name only. The Docker client copies the exported GITLAB_PERSONAL_ACCESS_TOKEN into the container.
docker run -i --rm \
-e HOST=0.0.0.0 \
-e GITLAB_PERSONAL_ACCESS_TOKEN \
-e GITLAB_API_URL="https://gitlab.com/api/v4" \
-e GITLAB_PERMISSION_MODE=readonly \
-e GITLAB_TOOLSETS=core,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=core,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_OAUTHabove.
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:
- A publicly accessible HTTPS server URL (
MCP_SERVER_URL) — use ngrok for local testing - A pre-registered GitLab OAuth application with
api(orread_api) scopes — Go toAdmin 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_ALLOWED_REDIRECT_URIS | optional | Client callback URLs that callback proxy mode will redirect to (default: Claude, ChatGPT, Cursor and loopback callbacks; defaults,<url> to add one) |
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 use the server (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_uriCheck the
redirect_uriin the browser URL. If it points to a client callback such ashttp://127.0.0.1:xxxxx/.../callback, enable:GITLAB_OAUTH_CALLBACK_PROXY=trueDo 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. Also trusted as download redirect targets (release assets, job artifacts, uploaded attachments); list private-network hosts here |
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_AUTHORIZATIONis not compatible with SSE transport.STREAMABLE_HTTP=trueis required.
Environment Variables
Use the dedicated reference for the full environment variable list:
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(orGITLAB_MCP_OAUTH=true),MCP_TRUST_PROXY=true(behind a reverse proxy),MAX_REQUESTS_PER_MINUTE=300,MCP_SERVER_URLorMCP_ALLOWED_HOSTS,HOST,PORT - Multiple side-by-side deployments: set a distinct
MCP_SERVER_NAMEper 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_URLGITLAB_PERSONAL_ACCESS_TOKENGITLAB_USE_OAUTHREMOTE_AUTHORIZATIONMCP_TRUST_PROXYMAX_REQUESTS_PER_MINUTEMAX_SESSIONSMCP_ALLOWED_HOSTSMCP_ALLOWED_ORIGINSGITLAB_MCP_OAUTHGITLAB_OAUTH_CALLBACK_PROXYGITLAB_OAUTH_ALLOWED_REDIRECT_URISOAUTH_REGISTER_RATE_LIMIT_PER_HOUROAUTH_STATELESS_MODEOAUTH_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.
SSE session limits
GET /sse is subject to the same remote-transport controls as Streamable HTTP:
- Capacity: at most
MAX_SESSIONSconcurrent SSE sessions (default 1000); further connections get503. - Creation rate limit: new connections are limited to
MAX_REQUESTS_PER_MINUTEper client IP (default 60); excess connections get429. - Idle timeout: a session that receives no
POST /messagesrequest forSESSION_TIMEOUT_SECONDS(default 1 hour) is closed, so an idle client must reconnect instead of holding a capacity slot. Unlike Streamable HTTP, holding the SSE stream open does not count as activity. /healthreturns503withstatus: "degraded"while the instance is at capacity.
Tune these with MAX_SESSIONS, MAX_REQUESTS_PER_MINUTE, and SESSION_TIMEOUT_SECONDS.
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:
/mcprequests are limited toMAX_REQUESTS_PER_MINUTEper 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_SESSIONSconcurrent 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).
- Go to your GitLab instance → Admin Area > Applications (instance-wide) or User Settings > Applications (personal)
- Create a new application with:
- Confidential: unchecked
- Scopes:
api,read_api,read_user(or whichever scopes you intend to request viaGITLAB_OAUTH_SCOPES)
- Save and copy the Application ID — this is your
GITLAB_OAUTH_APP_ID
How it works:
- User adds your MCP server URL in Claude.ai
- Claude.ai discovers OAuth endpoints via
/.well-known/oauth-authorization-server - Claude.ai registers itself via Dynamic Client Registration (
POST /register) — handled locally by the MCP server (each client gets a virtual client ID) - Claude.ai redirects the user's browser to GitLab's login page using the pre-registered OAuth application
- User authenticates; GitLab redirects back to
https://claude.ai/api/mcp/auth_callback - Claude.ai sends
Authorization: Bearer <token>on every MCP request - 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 the effective permission mode is readonly). 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=trueis 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_AUTHORIZATIONmode (SESSION_TIMEOUT_SECONDS,MAX_REQUESTS_PER_MINUTE,MAX_SESSIONS) - DCR rate limiting:
POST /registeris limited toOAUTH_REGISTER_RATE_LIMIT_PER_HOURper client IP (default 20/hour). Separate from/mcplimits and GitLab API quotas. See environment-variables.md. - Header auth fallback: when
Private-TokenorJOB-TOKENrequest 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: Beareris always treated as an OAuth token — usePrivate-Tokenfor 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, 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 🛠️
Click to expand
merge_merge_request- Merge a merge requestapprove_merge_request- Approve a merge requestunapprove_merge_request- Unapprove a merge requestget_merge_request_approval_state- Get merge request approval details including approversget_merge_request_conflicts- Get the conflicts of a merge requestlist_merge_request_pipelines- List pipelines for a merge request with paginationexecute_graphql- Execute a GitLab GraphQL querycreate_or_update_file- Create or update a file in a GitLab projectsearch_repositories- Search for GitLab projectscreate_repository- Create a new GitLab projectcreate_group- Create new group or subgroupget_file_contents- Get contents of a file or directory from a GitLab projectpush_files- Push multiple files in a single commitcreate_issue- Create a new issuecreate_merge_request- Create a new merge requestfork_repository- Fork a project to your account or specified namespacecreate_branch- Create a new branchget_branch- Get branch details (commit, protection status)list_branches- List branches in project with search filterdelete_branch- Delete branch from projectlist_protected_branches- List protected branches in a project, supports search filterget_protected_branch- Get details of a single protected branch (access levels, force push settings)protect_branch- Protect a repository branch (set push/merge/unprotect access levels)unprotect_branch- Remove protection from a previously protected branchupdate_default_branch- Change the default branch of a projectget_merge_request- Get details of a merge request (merge_request_iid or source_branch required). Set include_summaries=true for deployment/commit/approval summariesget_merge_request_diffs- Get the changes/diffs of a merge request (merge_request_iid or source_branch required)list_merge_request_changed_files- List changed file paths in a merge request without diff content (merge_request_iid or source_branch required)list_merge_request_diffs- List merge request diffs with pagination (merge_request_iid or source_branch required)get_merge_request_file_diff- Get diffs for specific files from a merge request (merge_request_iid or source_branch required)list_merge_request_versions- List all versions of a merge requestget_merge_request_version- Get a specific version of a merge requestget_branch_diffs- Get diffs between two branches or commitsupdate_merge_request- Update a merge request (merge_request_iid or source_branch required)create_note- Create a new note (comment) to an issue or merge requestcreate_merge_request_thread- Create a new thread on a merge requestresolve_merge_request_thread- Resolve a thread on a merge requestmr_discussions- List discussion items for a merge requestget_merge_request_discussion- Get a single discussion item for a merge requestdelete_merge_request_discussion_note- Delete a discussion note on a merge requestupdate_merge_request_discussion_note- Update a discussion note on a merge requestcreate_merge_request_discussion_note- Add a new discussion note to an existing merge request threadcreate_merge_request_note- Add a new note to a merge requestdelete_merge_request_note- Delete an existing merge request noteget_merge_request_note- Get a specific note for a merge requestget_merge_request_notes- List notes for a merge requestupdate_merge_request_note- Modify an existing merge request noteget_draft_note- Get a single draft note from a merge requestlist_draft_notes- List draft notes for a merge requestcreate_draft_note- Create a draft note for a merge requestupdate_draft_note- Update an existing draft notedelete_draft_note- Delete a draft notepublish_draft_note- Publish a single draft notebulk_publish_draft_notes- Publish all draft notes for a merge request. Optionally sets reviewer_state and posts a summary note (GitLab 19.2+). Can set reviewer_state even with no drafts.list_merge_request_emoji_reactions- List all emoji reactions on a merge requestlist_merge_request_note_emoji_reactions- List all emoji reactions on a merge request note. Pass discussion_id for discussion thread replies.create_merge_request_emoji_reaction- Add an emoji reaction to a merge request (e.g. thumbsup, rocket, eyes)delete_merge_request_emoji_reaction- Remove an emoji reaction from a merge requestcreate_merge_request_note_emoji_reaction- Add an emoji reaction to a merge request note. Pass discussion_id for discussion thread replies.delete_merge_request_note_emoji_reaction- Remove an emoji reaction from a merge request note. Pass discussion_id for discussion thread replies.update_issue_note- Modify an existing issue thread notecreate_issue_note- Add a note to an issue, optionally replying to a discussion threadlist_issue_emoji_reactions- List all emoji reactions on an issuelist_issue_note_emoji_reactions- List all emoji reactions on an issue note. Pass discussion_id for discussion thread replies.create_issue_emoji_reaction- Add an emoji reaction to an issue (e.g. thumbsup, rocket, eyes)delete_issue_emoji_reaction- Remove an emoji reaction from an issuecreate_issue_note_emoji_reaction- Add an emoji reaction to an issue note. Pass discussion_id for discussion thread replies.delete_issue_note_emoji_reaction- Remove an emoji reaction from an issue note. Pass discussion_id for discussion thread replies.list_issues- List issues (default: created by current user; use scope='all' for all)my_issues- List issues assigned to the authenticated userget_issue- Get details of a specific issue. Returns the issue with a slim nested milestone by default; set full_response=true for the complete milestone objectupdate_issue- Update an issue. Returns a slim confirmation by default; set full_response=true for the complete updated issue objectupdate_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 dry_run to preview changes and create_note to summarize updates.delete_issue- Delete an issuelist_todos- List GitLab to-do items for the current usermark_todo_done- Mark a GitLab to-do item as donemark_all_todos_done- Mark all pending GitLab to-do items as done for the current userlist_issue_links- List all issue links for a specific issuelist_issue_discussions- List discussions for an issueget_issue_link- Get a specific issue linkcreate_issue_link- Create an issue link between two issuesdelete_issue_link- Delete an issue linklist_namespaces- List all namespaces (users and groups) available to the current user. Filter by kind='group' for groups only.get_namespace- Get details of a namespace (user or group) by ID or path. Groups are namespaces with kind='group'.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.get_project- Get details of a specific project
// faq
What is gitlab-mcp?
MCP server for GitLab: 100+ tools for projects, MRs, issues, pipelines, wikis and more via the GitLab REST/GraphQL API. It is open-source on GitHub.
Is gitlab-mcp free to use?
gitlab-mcp is open-source under the MIT license, so it is free to use.
What category does gitlab-mcp belong to?
gitlab-mcp is listed under mcp-servers in the Claudeers registry of Claude-compatible tools.
// embed badge
[](https://claudeers.com/gitlab-mcp)
// retro hit counter
[](https://claudeers.com/gitlab-mcp)
// reviews
// guestbook
// related in MCP Servers
f.k.a. Awesome ChatGPT Prompts. Share, discover, and collect prompts from the community. Free and open source — self-host for your organization with complete…
A cross-platform desktop All-in-One assistant for Claude Code, Codex, OpenCode, OpenClaw, Gemini CLI & Hermes Agent. Only official website: ccswitch.io
🪨 why use many token when few token do trick — Claude Code skill that cuts 65% of tokens by talking like caveman
An open-source AI agent that brings the power of Gemini directly into your terminal.
// built by
2 of its contributors also build on official projects — inspector, python-sdk, typescript-sdk
→ see how gitlab-mcp connects across the ecosystem