A Model Context Protocol (MCP) server that connects AI assistants (Claude, Cursor, VS Code + Copilot, and any MCP client) to GitLab.com or self-managed GitLab instances. Covers the full REST API v4 and GraphQL with automatic edition gating — roughly 850 to 1070 tools depending on the GitLab tier — plus 45 MCP resources, 37 prompts, argument completions, and progress notifications. Single static binary, stdio and HTTP transports, read-only and safe (mutation-preview) modes, and an interactive setup wizard (gitlab-mcp-server --setup) that auto-configures most MCP clients.
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.
> "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, one-liners, and defaults — is in (no interactive wizard required).
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 --http=false
Or install the native binary first, then register it:
# 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
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.
🪶 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).
3 MCP capabilities (completions, progress, elicitation) and 50 SVG tool icons 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 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)
32 base / 49 Ultimate / 50 GitLab.com Ultimate
Domain-grouped dispatchers with an action parameter.
Individual (individual)
~847 Free/CE · ~999 Premium · 1065–1071 Ultimate
One MCP tool per GitLab operation; needs a large context window.
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.
Configuration (TOOL_SURFACE / CAPABILITY_SURFACE)
Tier
Visible tools
Reachable actions
META_PARAM_SCHEMA
Tool schema tokens
Shared tokens
Total tokens
dynamic / full (default)
Free/CE
2
851
n/a
2,180
31,758
33,938
dynamic / minimal
Free/CE
2
851
n/a
2,180
1,088
3,268
dynamic / full (default)
Premium
2
1,003
n/a
2,180
31,758
33,938
dynamic / minimal
Premium
2
1,003
n/a
2,180
1,088
3,268
dynamic / full (default)
Ultimate
2
1,069
n/a
2,180
31,758
33,938
dynamic / minimal
Ultimate
2
1,069
n/a
2,180
1,088
3,268
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
MCP Capability
Support
Tools
Up to 1071 individual / 32–50 meta
Resources
45 (static + templates)
Prompts
37 templates
Completions
Project, user, group, branch, tag
Logging
Structured (text/JSON) to stderr
Progress
Tool execution progress reporting
Elicitation
4 interactive creation wizards
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.
Enterprise meta & dynamic evaluation results
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.
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 via GITLAB_SKIP_TLS_VERIFY=true.
Is my data safe?
The server runs locally on your machine (stdio mode) or on your own infrastructure (HTTP mode). No data is sent to third parties — all API calls go directly to your GitLab instance. See SECURITY.md for details.
Can I use it in read-only mode?
Yes. Set GITLAB_READ_ONLY=true to disable all mutating tools (create, update, delete). Only read operations will be available.
Alternatively, set GITLAB_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_TIER=premium or GITLAB_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. The built-in setup wizard can auto-configure most clients.
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.26+
MCP SDK
github.com/modelcontextprotocol/go-sdk v1.6.1
GitLab Client
gitlab.com/gitlab-org/api/client-go/v2 v2.51.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.
> Repository mirror: GitHub is the canonical repository. A read-only mirror is available on GitLab.com for discoverability; please open contributions on GitHub.
