gitlab-mcp-server

README

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 (keychain)

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, no Docker) — open it with Claude Desktop 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, …)

Show JSON config for native binary and Docker

Native binary (Claude Desktop mcpServers, Cursor, etc.):

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

VS Code (.vscode/mcp.json, note servers + type):

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

Docker variant — replace "command"/"args" with:

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

Cline (VS Code) — open the Cline sidebar → MCP servers icon → Edit Global MCP, or edit the settings file directly:

• macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
• Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
• Windows: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

Cline uses the mcpServers shape shown above for the native binary.

For a shared, long-running HTTP deployment instead of per-user stdio, see HTTP Server Mode.

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 →)
• Proven with real models. An automated evaluator runs Anthropic, Google, OpenAI, and Qwen against live GitLab instances: 99.5% aggregate success across thousands of operations. (Results →)
• 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).

More: resources, prompts, and capabilities

• 45 MCP resources (read-only data: projects, issues, pipelines, MRs, branches, members, the surface-aware gitlab://tools manifest, and workflow best-practice guides). 26 resource kinds, single objects plus three single-parent lists, are also subscribable.
• 37 MCP prompts (code review, pipeline status, risk assessment, release notes, standup, analytics, audit, and more).
• 4 elicitation wizards (interactive issue/MR/release/project creation).
• 4 MCP capabilities (completions, progress, elicitation, and resource subscriptions — live resources/updated notifications, honored by polling) and 51 tool icons (50 domain icons plus the project mark) for visual identification in MCP clients.
• Pagination on every list endpoint with full metadata.

Tool surfaces

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

Surface	Visible tools	Best for
Dynamic (default)	2 (gitlab_find_action, gitlab_execute_action)	Lowest token cost; reaches the full catalog via find/execute.
Meta-tools (meta)	34 base / 51 Ultimate / 52 GitLab.com Ultimate	Domain-grouped dispatchers with an action parameter.
Individual (individual)	~866 Free/CE · ~1019 Premium · 1085–1091 Ultimate	One MCP tool per GitLab operation; needs a large context window.

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_TOOLS unset, 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.

Configuration (GITLAB_MCP_TOOL_SURFACE / GITLAB_MCP_CAPABILITY_SURFACE)	Tier	Visible tools	Reachable actions	GITLAB_MCP_META_PARAM_SCHEMA	Tool schema tokens	Shared tokens	Total tokens
dynamic / full (default)	Free/CE	2	870	n/a	1,524	8,835	10,359
dynamic / minimal	Free/CE	2	870	n/a	1,524	170	1,694
dynamic / full (default)	Premium	2	1,023	n/a	1,524	8,835	10,359
dynamic / minimal	Premium	2	1,023	n/a	1,524	170	1,694
dynamic / full (default)	Ultimate	2	1,089	n/a	1,524	8,835	10,359
dynamic / minimal	Ultimate	2	1,089	n/a	1,524	170	1,694

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

MCP Capability	Support
Tools	Up to 1091 individual / 34–52 meta
Resources	45 (static + templates)
Prompts	37 templates
Completions	18 argument names, among them projects, groups, users, branches, tags, MRs, issues, pipelines, jobs, labels, milestones and SHAs
Server logs	Structured (text/JSON) to stderr — not the MCP logging capability, which is deprecated (SEP-2577) and deliberately not advertised
Progress	Tool execution progress reporting
Elicitation	4 interactive creation wizards
Subscriptions	resources/updated by polling, 26 resource kinds

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. It runs schema-only checks against the tool catalog or executes validated model tool calls through MCP against Docker GitLab CE or licensed Enterprise instances populated with fixtures. It measures whether each model chooses the correct action, sends valid parameters, recovers from actionable GitLab errors, and respects destructive-action safeguards — across Anthropic, Google, OpenAI, and Qwen.

Current published result: Docker CE dynamic 20260627-232303.

Provider	Model	Compatibility	Tool accuracy	Recovery	Docker live status
Anthropic	claude-haiku-4-5-20251001	OK	100.0%	100.0% (2/2)	100.0% final across 555 ops
Google	gemini-flash-latest	OK	100.0%	100.0% (4/4)	100.0% final across 555 ops
OpenAI	gpt-5.4-nano	Review	99.3%	84.6% (11/13)	98.0% final across 555 ops
Qwen	qwen3.6-flash	OK	100.0%	100.0% (5/5)	100.0% final across 555 ops

The published model-evaluation set covers 596 task attempts and 2220 expected MCP operations. Across the selected reports, models emitted 2265 tool calls over 2265 model requests, with 99.5% aggregate final success. See AI Model Evaluation Results for the detailed current matrix.

Meta-tools and Enterprise evaluation results

No CE meta-tools run has been published yet: make eval-surfaces-docker SURFACE=meta followed by --publish-docs fills this block.

Current published result: Docker Enterprise meta 20260527.

Provider	Model	Compatibility	Tool accuracy	Recovery	Docker live status
Anthropic	claude-haiku-4-5-20251001	OK	100.0%	100.0% (1/1)	100.0% final across 84 ops
Google	gemini-flash-latest	Review	78.2%	100.0% (7/7)	100.0% final across 84 ops
OpenAI	gpt-5.4-nano	Review	100.0%	100.0% (4/4)	100.0% final across 84 ops
Qwen	qwen3.6-flash	OK	100.0%	100.0% (1/1)	100.0% final across 84 ops

The published model-evaluation set covers 92 task attempts and 336 expected MCP operations. Across the selected reports, models emitted 345 tool calls over 350 model requests, with 100.0% aggregate final success. See AI Model Evaluation Results for the detailed current matrix.

Current published result: Docker Enterprise dynamic 20260628-015421.

Provider	Model	Compatibility	Tool accuracy	Recovery	Docker live status
Anthropic	claude-haiku-4-5-20251001	OK	100.0%	100.0% (1/1)	100.0% final across 202 ops
Google	gemini-flash-latest	OK	100.0%	100.0% (2/2)	100.0% final across 202 ops
OpenAI	gpt-5.4-nano	OK	100.0%	No repairs	100.0% final across 202 ops
Qwen	qwen3.6-flash	OK	100.0%	100.0% (1/1)	100.0% final across 202 ops

The published model-evaluation set covers 124 task attempts and 808 expected MCP operations. Across the selected reports, models emitted 817 tool calls over 817 model requests, with 100.0% aggregate final success. See AI Model Evaluation Results for the detailed current matrix.

Documentation

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

Document	Description
Getting Started	Install paths, first query, per-client configuration
Installation	Every install channel (binary, Homebrew, winget, Docker, npm, PyPI, NuGet, .mcpb, Agent Plugins, hosted), verification, upgrade and uninstall
IDE Configuration	Per-client stdio, HTTP legacy, and HTTP OAuth examples
Configuration	Environment variables, transport modes, TLS
Environment Variables	Exhaustive environment variable table with defaults and examples
CLI Reference	All command-line flags, exit codes, and runtime examples
HTTP Server Mode	Shared HTTP deployments, authentication, server pool isolation
OAuth App Setup	GitLab OAuth application, scopes, redirect URIs, and which clients can complete a flow
CI/CD	Running the server inside GitLab CI and GitHub Actions pipelines
Output Format	The response contract every tool follows: content blocks, pagination, next steps
Error Handling	Error classification, GitLab message extraction, and the hints tools return
Tools Reference	All individual tools with input/output schemas, including GitLab.com-only Orbit
Meta-Tools	34/51/52 domain meta-tools with action dispatching
Dynamic Toolset	2-tool low-token mode with canonical action catalog, safety model, and examples
Resources	All 45 resources with URI templates
Prompts	All 37 prompts with arguments and output format
Testing	Unit, E2E, schema model evaluation, Docker model evaluation, and curated model results
Security	Security model, token scopes, input validation
Architecture	System architecture, component design, data flow
Development Guide	Building, testing, CI/CD, contributing
Troubleshooting	Common startup, token, TLS, transport, and tool-discovery issues

FAQ

Does it work with self-hosted GitLab?

Yes. Set GITLAB_URL to your instance URL. When GITLAB_URL is omitted, stdio mode uses https://gitlab.com. Self-signed TLS certificates are supported by installing the CA in the system trust store or pointing SSL_CERT_FILE at a bundle; GITLAB_MCP_SKIP_TLS_VERIFY=true skips verification instead, and --auth-mode=oauth refuses it for a non-loopback instance.

Is my data safe?

When you run it yourself, locally over stdio or on your own infrastructure over HTTP, every request goes to your GitLab instance and nowhere else. There is no update check, no license check and no telemetry: your instance is the only host this server contacts.

The exception is the hosted endpoint: using https://mcp.jmrp.io/gitlab means your token and every request pass through that machine. Nothing is stored there, but it is someone else's server, which is why the hosted section says to keep using it locally.

See PRIVACY.md for the full data-flow statement, and SECURITY.md for the security model.

Can I use it in read-only mode?

Yes. Set GITLAB_MCP_READ_ONLY=true to disable all mutating tools (create, update, delete). Only read operations will be available.

Alternatively, set GITLAB_MCP_SAFE_MODE=true for a dry-run mode: mutating tools remain visible but return a structured JSON preview instead of executing. Useful for auditing, training, or reviewing what an AI assistant would do.

What GitLab editions are supported?

Both Community Edition (CE) and Enterprise Edition (EE). Set GITLAB_MCP_TIER=premium or GITLAB_MCP_TIER=ultimate in stdio mode to enable additional tools for Premium/Ultimate features (DORA metrics, vulnerabilities, compliance, etc.); leave it unset to detect the tier from the instance license (fallback free). In HTTP mode, --tier can force the tier, otherwise it is detected per token+URL pool entry from the license.

How does it handle rate limiting?

The server includes retry logic with backoff for GitLab API rate limits. Errors are classified as transient (retryable) or permanent, with actionable hints in error messages.

Which AI clients are supported?

Any MCP-compatible client: VS Code + GitHub Copilot, Claude Desktop, Cursor, Claude Code, Windsurf, JetBrains IDEs, Zed, Kiro, and others. Each one's configuration snippet is in Getting Started, and the one-click buttons above cover the most common ones.

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.

Component	Technology
Language	Go 1.27+
MCP SDK	github.com/modelcontextprotocol/go-sdk v1.7.0
GitLab Client	gitlab.com/gitlab-org/api/client-go/v3 v2.59.0
Transport	stdio (default), HTTP (Streamable HTTP)

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.

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.

Unnecessary statistics — numbers nobody asked for

File counts

Category	Files	Lines
Source (.go, non-test)	1,243	266,336
Unit tests (_test.go)	732	436,538
End-to-end tests	246	66,458
Total	2,221	769,332

Functions

Category	Count
Source functions	9,766
. Exported (public)	3,070
. Unexported (private)	6,696
Unit test functions (TestXxx)	14,716
Subtests (t.Run(...))	5,962
End-to-end test functions	606

Ratios worth noting

Observation	Value
Test lines vs source lines	1.64× more tests than code
Average source file length	~214 lines
Average test file length	~596 lines
Comment lines in source	49,755 (~18.7% of source)
Test functions per source function	1.5×

Code patterns

Pattern	Count
if err != nil checks	8,165
defer statements	1,371
struct types defined	3,224
//nolint suppressions	349
TODO / FIXME / HACK comments	2

Project

Metric	Value
Go packages	269
Direct dependencies (go.mod)	32
Indirect dependencies	39

Hall of fame

Record	File
Longest source file	cmd/server/main.go. 4,667 lines
Longest test file	cmd/server/main_test.go. 10,664 lines

Because why not

Fact	Value
Source code printed at 55 lines/page	~4,842 pages of A4
Source lines mentioning "gitlab"	15,485 (impossible to avoid)
Longest function name in source	assertDynamicCompatibilityPolicyOwnedByActionCompat (51 chars)
Longest test function name	TestRequiredMissingAndUnknownParamNames_SchemaValidation_ReturnsSortedMissingAndUnknown (87 chars)

---

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