GitLab MCP Server
The default configuration costs 10,359 tokens of context on every GitLab tier; 1,694 with GITLAB_MCP_CAPABILITY_SURFACE=minimal. Measured, not estimated.
What it is
GitLab MCP Server is a Model Context Protocol server, written in Go, that lets an AI assistant work your GitLab for you: review merge requests, triage pipelines, manage issues, draft releases. It covers the REST v4 and GraphQL APIs and runs against GitLab.com or any self-hosted instance, Community or Enterprise Edition.
You talk to your assistant, not to the tools. One canonical action catalog is projected into three tool surfaces, so the same operations fit a low-token client, a domain-tool client, or one tool per operation — and the assistant picks arguments from typed schemas, not from prose.
It ships as one static binary (or a container) for Linux, macOS and Windows, speaking stdio for a local client or HTTP for a shared, multi-user deployment.
Who it is for
- Anyone who reviews merge requests and would rather ask for the risky diff in a sentence than open six tabs.
- People running an MCP client already — Claude Code, Claude Desktop, Cursor, VS Code, or their own agent.
- Teams on self-hosted GitLab, Community Edition included: tier-gated tools register only when the instance licence carries them.
- Operators who want one shared HTTP endpoint with per-token isolation instead of a binary per laptop.
What it is not
- Not a way around your permissions. Every call is made with your token, and what its scopes and your instance licence forbid stays forbidden.
- Not an official GitLab product. It talks to GitLab's documented APIs and says so; GitLab is a trademark of GitLab Inc.
- Not obliged to write. Read-only mode removes every mutating action, and safe mode turns each one into a preview instead of an execution.
- Not a black box. Every figure on this page is generated from the catalog, and the model-facing behaviour is measured by a live evaluation suite.
What it looks like in use
One command to connect it, plain sentences after that.
Connect it to Claude Code
Docker keeps it zero-install; a native binary works the same way. The token is never on the registration command line: the container reads it from the environment, and a native binary also reads ~/.gitlab-mcp-server.env. Other clients take the same server over stdio or HTTP.
export GITLAB_TOKEN=glpat-xxxxclaude mcp add gitlab --env GITLAB_URL=https://gitlab.example.com --transport stdio \ -- docker run -i --rm -e GITLAB_URL -e GITLAB_TOKEN \ ghcr.io/jmrplens/gitlab-mcp-server:latestThen just ask
The assistant chooses the tool and the arguments; the server returns structured JSON for the model and formatted Markdown for you.
| You say | The server does |
|---|---|
“Show open merge requests in my-org/backend that need review” | Lists MRs with authors, assignees and pipeline state, as a table with links. |
“Why did the pipeline fail on feature/auth?” | Finds the failing job, reads its log, and summarises the error with a suggested fix. |
| “Create a P1 bug for the auth regression and assign it to @alice” | Creates the issue with labels and assignee — or, in safe mode, shows the exact call it would make. |
| “Draft release notes for v2.1.0 against v2.0.0” | Compares the tags, groups the commits and merge requests, and drafts the changelog. |
One catalog, three surfaces
Every operation lives once, in a canonical action catalog, and is projected into the surface that fits your client's context budget. The counts are generated from the catalog, never typed.
| Surface | Tools | When to use it |
|---|---|---|
| Dynamicfind_action + execute_action — the default | 2 | Smallest context footprint: the assistant searches the catalog, reads the exact schema, then executes the canonical action. |
| Meta-toolsone dispatcher per domain | 34–52 | A visible tool per domain (projects, issues, MRs, pipelines…) with routed actions inside — the balanced middle. |
| Individualone tool per operation | 866–1,091 | Everything visible at once, for clients that prefer a flat list and have the context to hold it. |
Ranges span the instance tier: the lower bound is Free/CE, the upper is GitLab.com Ultimate with Orbit. Premium and Ultimate tools register only when the connected instance licence carries them.
Start here
Three steps from nothing to an assistant with hands on GitLab.
Install
Docker, Homebrew, winget, a release binary, or the Claude Desktop extension — pick the one your machine likes.
Getting startedPoint it at GitLab
A personal access token and your instance URL are the whole configuration. Both go in ~/.gitlab-mcp-server.env, which the server reads for what its environment does not already carry.
Client configurationGITLAB_URL=https://gitlab.example.comGITLAB_TOKEN=glpat-xxxxPick a surface
The dynamic default fits any client. Prefer domain tools or one tool per operation? One environment variable switches the surface.
Tool surfacesGITLAB_MCP_TOOL_SURFACE=dynamic|meta|individual
Frequently asked questions
What is GitLab MCP Server?
GitLab MCP Server is a free, open-source Model Context Protocol server that lets AI assistants interact with GitLab through natural language. It exposes the GitLab REST v4 and GraphQL APIs as MCP tools, so an assistant can review merge requests, triage pipelines, manage issues, and draft releases on your behalf. It ships as a single Go binary and runs locally over stdio or remotely over HTTP.
Which AI assistants work with GitLab MCP Server?
Any MCP-compatible client works — including VS Code with GitHub Copilot, Claude Desktop, Cursor, and Claude Code, plus any other client that speaks the Model Context Protocol over stdio or HTTP transport. Configuration is a small JSON snippet per client.
Is GitLab MCP Server free and open source?
Yes. GitLab MCP Server is free and open source under the MIT license, with the full source on GitHub. There is no paid tier of the server itself; GitLab Premium or Ultimate features are gated only by your own GitLab instance license, not by the MCP server.
Does it work with self-hosted GitLab and Community Edition?
Yes. It works with GitLab.com and self-hosted instances, and with both Community Edition and Enterprise Edition. Point it at any GitLab URL with a personal access token. Premium and Ultimate tools register only when the connected instance is licensed for them.