gitlab-mcp-server

GitLab MCP Server

Connect your AI assistant to GitLab so it can review merge requests, triage pipelines, manage issues, and draft releases — in plain language. One static binary (or a container), 1000+ GitLab tools over the full REST + GraphQL API, working with Claude, Cursor, VS Code, and any MCP client.

You talk to your AI assistant; it does the GitLab work. No project IDs, API endpoints, or JSON to remember.

10,359 tokens of startup context by default, the same on every GitLab tier (1,694 with GITLAB_MCP_CAPABILITY_SURFACE=minimal). Two tools reach the whole catalog; measured with the cl100k_base tokenizer and verified in CI on every commit. How it is measured

"Review merge request !15 — is it safe to merge?" · "Why did the last pipeline fail?" · "List open issues assigned to me" · "Generate release notes from v1.0 to v2.0"

🤖 Using an AI assistant? Give it this repository URL and ask it to install the server for your client. Everything a model needs to do it headlessly — the declarative per-client config, claude mcp add one-liners, and defaults — is in llms.txt (no interactive wizard required).

Install in 60 seconds

Pick one. Each path ends with you typing a prompt to your assistant. Every channel has a full guide: Installation.

Want to look before installing? The browser inspector signs in with OAuth and calls the hosted endpoint read-only from a browser tab — nothing downloaded. Running it yourself is still the way to keep using it.

One-click install

Client	One-click button	Token step
VS Code		prompts you (masked)
VS Code Insiders		prompts you (masked)
Cursor		edit YOUR_GITLAB_TOKEN
LM Studio		edit YOUR_GITLAB_TOKEN
Kiro		edit YOUR_GITLAB_TOKEN
Claude Desktop		settings UI

Each button registers the Docker-based server (auto-pulls the image on first run; you need Docker installed). The Claude Desktop row instead downloads a native .mcpb desktop extension (macOS universal, Windows, and Linux amd64 and arm64; no Docker). Open it with Claude Desktop, or on Linux use Extensions > Install Extension..., and fill in the settings. Need a token? Create a Personal Access Token with the api scope. Self-managed GitLab? Add a GITLAB_URL env var in your client's MCP config after install.

Claude Code (claude mcp add)

Docker (no install — pulls the image on first run):

claude mcp add gitlab --env GITLAB_TOKEN=glpat-xxxx --transport stdio \
  -- docker run -i --rm -e GITLAB_TOKEN ghcr.io/jmrplens/gitlab-mcp-server:latest

Or install the native binary first, then register it:

# Any platform (npm/pnpm) — downloads only your platform's prebuilt binary
npx -y @jmrp.io/gitlab-mcp-server          # zero install; clients launch it directly
npm install -g @jmrp.io/gitlab-mcp-server  # or install globally (npm)
pnpm add -g @jmrp.io/gitlab-mcp-server     # or globally (pnpm)
# Any platform (Python: uv/pipx/pip) — platform wheel carrying the same native binary
uvx jmrplens-gitlab-mcp-server             # zero install; clients launch it directly
pipx install jmrplens-gitlab-mcp-server    # or install globally (pipx)
pip install jmrplens-gitlab-mcp-server     # or into the active environment (pip)
# Linux wheels need glibc; on musl systems such as Alpine use the Docker image instead
# Any platform (.NET 10 SDK) — a .NET tool whose entry point is the same native binary
dnx gitlab-mcp-server                      # zero install; clients launch it directly
dotnet tool install -g gitlab-mcp-server   # or install globally (dotnet tool)
# macOS/Linux (Homebrew)
brew install jmrplens/tap/gitlab-mcp-server
# Linux/macOS (script)
curl -fsSL https://raw.githubusercontent.com/jmrplens/gitlab-mcp-server/main/scripts/install.sh | sh
# Windows (winget)
winget install --id jmrplens.gitlab-mcp-server -e
# Windows (PowerShell)
irm https://raw.githubusercontent.com/jmrplens/gitlab-mcp-server/main/scripts/install.ps1 | iex

claude mcp add gitlab --env GITLAB_TOKEN=glpat-xxxx -- gitlab-mcp-server

Clients that launch servers with npx, uvx or dnx need no install at all — point them at npx -y @jmrp.io/gitlab-mcp-server, uvx jmrplens-gitlab-mcp-server or dnx gitlab-mcp-server.

Self-managed GitLab? Add --env GITLAB_URL=https://gitlab.example.com (and, for a self-signed certificate, mount the CA and set --env SSL_CERT_FILE=/path/to/ca-bundle.crt; GITLAB_MCP_SKIP_TLS_VERIFY=true is the blunt alternative, and OAuth mode refuses it for a non-loopback instance).

Run it once to check the install

Started in a terminal, or double-clicked on Windows, with no GITLAB_TOKEN set, the binary prints what it is and what it needs and waits for Enter, so you can confirm the install before configuring anything. Configuration itself lives in your MCP client's JSON, below.

Manual JSON (Claude Desktop, Cursor, VS Code, …)

{
  "mcpServers": {
    "gitlab": {
      "command": "/path/to/gitlab-mcp-server",
      "env": { "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx" }
    }
  }
}

{
  "servers": {
    "gitlab": {
      "type": "stdio",
      "command": "/path/to/gitlab-mcp-server",
      "env": { "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx" }
    }
  }
}

"command": "docker",
"args": ["run", "-i", "--rm", "-e", "GITLAB_TOKEN", "ghcr.io/jmrplens/gitlab-mcp-server:latest"]

Try it without installing anything (hosted endpoint)

A public instance runs at https://mcp.jmrp.io/gitlab — nothing to install, no account beyond your own GitLab token. Point any HTTP-capable MCP client at it:

{
  "mcpServers": {
    "gitlab": {
      "type": "http",
      "url": "https://mcp.jmrp.io/gitlab",
      "headers": { "Authorization": "Bearer glpat-xxxxxxxxxxxx" }
    }
  }
}

The endpoint runs in OAuth mode, so the credential travels as Authorization: Bearer — a GitLab personal access token works there, verified exactly like an OAuth one, which is what keeps clients with no OAuth flow (and headless use) working. It travels per request and is never stored on the server. A client that speaks the OAuth flow needs no header at all: the 401 carries an RFC 9728 challenge it follows to authorize in the browser. PRIVATE-TOKEN is the legacy-mode header and is not accepted here; the instance is fixed to https://gitlab.com, so GITLAB-URL is ignored.

A read_api token is accepted and served a read-only tool surface — the write check is per action, so a credential that cannot break anything is a supported way to use the endpoint rather than a rejected one.

Two pages make it easier still. The server card lists the whole catalog with no credential at all and carries copy-paste config for Claude Code, Cursor and VS Code — including the OAuth client ID those clients need. The browser inspector calls the same endpoint read-only from a browser tab: sign in with OAuth, pick a tool, read the raw JSON-RPC it returns — nothing installed.

It is the fastest way to try the server, and the right way to keep using it is still locally (any option above) — for one concrete reason, not as a disclaimer: your token and every request pass through someone else's machine. Running it locally means your credentials and your GitLab traffic never leave your computer, which also makes it the only sensible option for a private self-managed instance.

The endpoint is stateless streamable HTTP on the default dynamic surface: POST is the transport and an authenticated GET answers 405 by design; with no credential, any method answers 401 carrying the RFC 6750 challenge an OAuth client follows — a bare curl that gets 401 is the endpoint working, not failing. https://mcp.jmrp.io/gitlab/health needs no credential and answers 200 with {"status":"ok",…}. A self-hosted HTTP deployment can also run --auth-mode=oauth --gitlab-url=https://gitlab.com --public-url=https://mcp.example.com/mcp (both are required: OAuth needs a fixed instance, and --public-url is the RFC 9728 resource identifier — pass exactly the URL your clients are configured with, since a client discards metadata naming a different one), where clients discover GitLab as the authorization server through that metadata and authorize in the browser instead of copying tokens — see OAuth App Setup. It is one of the servers listed at mcp.jmrp.io, a directory of the MCP servers I maintain, each reachable at its own endpoint; https://mcp.jmrp.io/servers.json is the same list for automated clients.

It is a personal service, run by one person and offered as-is: no SLA, no support channel, and no promise it is unchanged next week. It adds no quota of its own — every call spends GitLab.com's own limits, under your own token. And it moves on its own, normally to the newest release, so what it serves is never a pinned version.

Then just ask: open your AI client and try "List my GitLab projects." See the Getting Started guide for per-client details and more example prompts.

Why this server

• Plain-language GitLab. The AI translates "is MR !15 safe to merge?" into the right API calls. You don't touch endpoints, IDs, or JSON.
• The whole platform — 1000+ tools. Broad GitLab REST v4 + GraphQL coverage: projects, branches, tags, releases, merge requests, issues, pipelines, jobs, groups, users, wikis, environments, deployments, packages, container registry, runners, feature flags, CI/CD variables, security, admin, tokens, and more.
• Low-token by default. The default dynamic surface exposes just 2 tools (find + execute) while reaching the full catalog — so it fits any client's context window. (Token footprint →)
• Safe by design. Read-only mode, safe mode (dry-run preview of every mutation), TLS options for self-hosted GitLab, and continuous SonarCloud quality/security gates.
• Runs anywhere. One static binary or container; Windows, Linux & macOS; amd64 & arm64; stdio (desktop) and HTTP (remote).

Tool surfaces

The server can present GitLab in three shapes, controlled by GITLAB_MCP_TOOL_SURFACE. The default needs no configuration.

Tool counts scale with your GitLab edition (GITLAB_MCP_TIER); higher tiers expose more actions. See Dynamic Toolset and Meta-Tools Reference for the ranking model, safety guards, and full catalogs. For dynamic runs where resources dominate context, set GITLAB_MCP_CAPABILITY_SURFACE=minimal.

Token Footprint

Measured with go run ./cmd/audit_tokens/ -footprint against the current catalog. Totals estimate startup context visible to an MCP client: visible tool schemas plus shared resources and prompts, using the cl100k_base tokenizer (GPT-4/GPT-3.5 encoding). For the full matrix (meta and individual surfaces, all GITLAB_MCP_META_PARAM_SCHEMA modes), see Token Footprint Reference.

Default configuration: with GITLAB_MCP_TOOL_SURFACE unset or GITLAB_MCP_TOOL_SURFACE=dynamic, GITLAB_MCP_CAPABILITY_SURFACE=full, GITLAB_MCP_META_PARAM_SCHEMA=opaque, and GITLAB_MCP_TIER unset (detected, fallback free), the server uses the dynamic find/execute surface. Use GITLAB_MCP_TOOL_SURFACE=meta only when you explicitly want domain meta-tools; use GITLAB_MCP_TOOL_SURFACE=individual only when your client can handle the full tool catalog.

Rows use the base Community Edition catalog unless the Tier column says otherwise. GITLAB_MCP_TIER controls which actions are available; higher tiers expose more tools and thus more reachable actions.

Compatibility

Tested with: VS Code + GitHub Copilot, Claude Desktop, Claude Code, Cursor, Windsurf, JetBrains IDEs, Zed, Kiro, Cline. See the full Compatibility Matrix.

AI Model Tool-Use Evaluation

The project includes an automated evaluator for model-facing MCP quality, and it currently publishes no result. Every figure this section used to carry has been withdrawn, including the 99.5% aggregate success this README led with.

They were withdrawn because the measurement did not measure what it claimed. One struct fed the stimulus the model was given, the environment it acted in, the scorer that graded it and the report at the same time, so parts of the corpus put the expected call in the prompt the scorer then checked against, repairs were made from an answer key the harness supplied, and the scorer compared parameter names rather than their values. A run could not have failed for the reasons it was meant to catch. The tables as they last stood can be read at commit 4587cbfb3; the account of what was wrong with them is kept in AI Model Evaluation Results.

The replacement is being built as a tagged package under test/e2e/ on the end-to-end harness, which already keeps the stimulus, the environment and the record apart. Numbers return here when that harness produces them.

Withdrawn. The CE dynamic table published here, last refreshed from a Docker run dated 20260627-232303, is readable at commit 4587cbfb3 and is not reproduced because the measurement behind it was unsound.

Documentation

Full documentation is at jmrp.io/docs/gitlab-mcp-server. Use this map for the source-of-truth reference on a specific area:

FAQ

Building from Source

git clone https://github.com/jmrplens/gitlab-mcp-server.git
cd gitlab-mcp-server
make build

The published container image is ghcr.io/jmrplens/gitlab-mcp-server:latest. See the Development Guide for cross-compilation, Docker Compose, and contributing guidelines.

Privacy Policy

The server runs entirely on your machine and has no telemetry, analytics, or backend of its own — data flows only between your MCP client and the GitLab instance you configure (plus an optional signed-binary update check against GitHub Releases). Your token is used solely to authenticate GitLab requests and is never logged. Full details: PRIVACY.md.

Upstream contributions

This server is built on GitLab's REST and GraphQL APIs, on client-go and on the MCP Go SDK. When building it turns up a gap in one of them, the fix goes upstream rather than staying a workaround here, so every other user of those projects gets it too:

• client-go: response fields GitLab sends that the SDK's structs did not model, found by holding each struct against what a running GitLab actually sends, and fixes such as a panic decoding an issue with no id (merge requests).
• GitLab: API documentation and response annotations corrected where they disagreed with what the API sends, a fix so a revoked GPG identity no longer verifies commits, and proposed additions such as cancelling an automatic merge (merge requests).
• MCP Go SDK: protocol conformance fixes around cancellation, protocol version negotiation and the initialize handshake (pull requests).

Every gap is tracked in docs/development/upstream-bugs.md: the upstream issue or merge request, whether it has merged and in which release, and the workaround this server carries until it ships.

Contributing & Security

• Contributing: see CONTRIBUTING.md for development guidelines, branch naming, commit conventions, and the PR process.
• Security: see SECURITY.md for the security policy and vulnerability reporting.
• Code of Conduct: see CODE_OF_CONDUCT.md (Contributor Covenant v2.1).

Repository mirror: GitHub is the canonical repository. A read-only mirror is available on GitLab.com for discoverability; please open contributions on GitHub.

Maintained by José M. Requena Plens · Project page · Hosted instance: mcp.jmrp.io/gitlab