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.

"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.

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

Each button registers the Docker-based server (auto-pulls the image on first run; you need Docker installed). 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 --http=false

Or install the native binary first, then register it:

# Linux/macOS
curl -fsSL https://raw.githubusercontent.com/jmrplens/gitlab-mcp-server/main/scripts/install.sh | sh
# 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

Self-managed GitLab? Add --env GITLAB_URL=https://gitlab.example.com (and --env GITLAB_SKIP_TLS_VERIFY=true for self-signed certs).

Guided setup (any client, no flags to remember)

The binary ships a setup wizard that collects your GitLab token and configures your MCP client for you — ideal if you'd rather not edit JSON:

gitlab-mcp-server --setup

It auto-detects VS Code, Claude Desktop, Claude Code, Cursor, and Windsurf and writes the right config. On Windows, double-click the .exe to launch it.

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", "--http=false"]

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).

Tool surfaces

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

Tool counts scale with your GitLab edition (GITLAB_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 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 META_PARAM_SCHEMA modes), see Token Footprint Reference.

Default configuration: with TOOL_SURFACE unset or TOOL_SURFACE=dynamic, CAPABILITY_SURFACE=full, META_TOOLS unset, META_PARAM_SCHEMA=opaque, and GITLAB_TIER unset (detected, fallback free), the server uses the dynamic find/execute surface. Use TOOL_SURFACE=meta only when you explicitly want domain meta-tools; use 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_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. 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.

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.

Documentation

Full documentation is at jmrplens.github.io/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.

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.