GitLab MCP Server

A Model Context Protocol (MCP) server that exposes the entire GitLab API as MCP tools, resources, and prompts for AI assistants. Single static binary — zero dependencies.

Security first: Continuously monitored on SonarCloud with quality gates, coverage, and security scanning. Supports read-only mode, safe mode (dry-run preview), and self-hosted GitLab with TLS verification.

Token Footprint

Measured with go run ./cmd/audit_tokens/ against the current catalog. Totals estimate startup context visible to an MCP client: tool schemas plus shared resources and prompts, using a 200K-token context window as a reference.

Default configuration: with TOOL_SURFACE unset, META_TOOLS unset or true, and GITLAB_ENTERPRISE unset or false, the server uses base meta-tools. That means 33 visible tools, 855 reachable actions, and no Enterprise/Premium-only catalog.

Reachable actions include the five standalone utility actions (gitlab_discover_project plus four interactive creation flows). They are visible standalone tools in meta mode and folded into the dynamic catalog, which is why the catalog-only route count is 850 / 1005 while the comparable reachable-action count is 855 / 1010. dynamic and dynamic-3 expose the same current three-tool search/describe/execute surface. The experimental dynamic-2 comparison surface uses two visible tools and measures about 19,521 tokens with full capabilities or 1,507 tokens with CAPABILITY_SURFACE=minimal.

Highlights

• 1006 MCP tools on self-managed Enterprise/Premium, or 1011 on GitLab.com Enterprise/Premium with experimental Orbit Knowledge Graph support — broad GitLab REST API v4 + GraphQL coverage across 163 domain sub-packages: projects, branches, tags, releases, merge requests, issues, pipelines, jobs, groups, users, wikis, environments, deployments, packages, container registry, runners, feature flags, CI/CD variables, templates, admin settings, access tokens, deploy keys, Orbit, and more

• 32 meta-tools (47 on self-managed Enterprise/Premium, 48 on GitLab.com Enterprise/Premium) — domain-grouped dispatchers that reduce token overhead for LLMs (optional, enabled by default). A low-token dynamic mode can expose only gitlab_search_tools, gitlab_describe_tools, and gitlab_execute_tool while keeping the same canonical GitLab action catalog

• AI model tool-use evaluation — automated schema-only and Docker-backed runs against a populated GitLab CE instance measure tool/action selection, parameter shaping, recovery from GitLab errors, and destructive-action safety across Anthropic, Google, OpenAI, and Qwen. The current reviewed result is published in the managed evaluation block below; see AI Model Evaluation Results

• 11 sampling actions — LLM-assisted code review, issue analysis, pipeline failure diagnosis, security review, release notes, milestone reports, and more via gitlab_analyze meta-tool (MCP sampling capability)

• 4 elicitation tools — interactive creation wizards (issue, MR, release, project) with step-by-step user prompts

• 46 MCP resources — read-only data: user, groups, group members, group projects, projects, issues, pipelines, members, labels, milestones, branches, MRs, releases, tags, commits, file blobs, wiki pages, MR notes, MR discussions, meta-tool JSON Schemas, single-entity templates (issue, MR, branch, tag, release, label, milestone, commit, wiki page, deployment, environment, job, board, snippet, deploy key, feature flag, group label, group milestone), workspace roots, and 5 workflow best-practice guides

• 38 MCP prompts — AI-optimized: code review, pipeline status, risk assessment, release notes, standup, workload, user stats, team management, cross-project dashboards, analytics, milestones, audit

• 6 MCP capabilities — logging, completions, roots, progress, sampling, elicitation

• 50 tool icons — base64-encoded SVG icons (Sizes: ["any"]) on all tools, resources, and prompts for visual identification in MCP clients

• Pagination on all list endpoints with metadata (total items, pages, next/prev)

• Transports: stdio (default for desktop AI) and HTTP (Streamable HTTP for remote clients)

• Cross-platform: Windows, Linux & macOS, amd64 & arm64

• Self-hosted GitLab with self-signed TLS certificate support

Example Prompts

Once connected, just talk to your AI assistant in natural language:

"List my GitLab projects" "Show me open merge requests in my-app" "Create a merge request from feature-login to main" "Review merge request !15 — is it safe to merge?" "List open issues assigned to me" "What's the pipeline status for project 42?" "Why did the last pipeline fail?" "Generate release notes from v1.0 to v2.0"

The server handles the translation from natural language to GitLab API calls. You do not need to know project IDs, API endpoints, or JSON syntax — the AI assistant figures that out for you. See Usage Examples for more scenarios.

Quick Start

1. Get the server

Download the latest binary for your platform from GitHub Releases and make it executable:

chmod +x gitlab-mcp-server-*  # Linux/macOS only

Or pull the published container image:

docker pull ghcr.io/jmrplens/gitlab-mcp-server:latest

2. Configure GitLab access

Recommended: Run the built-in setup wizard — it configures your GitLab connection and MCP client in one step:

./gitlab-mcp-server --setup

Tip: The wizard supports Web UI, Terminal UI, and plain CLI modes. On Windows, double-click the .exe to launch the wizard automatically.

Manual setup only needs a GitLab Personal Access Token with api scope:

GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx

GITLAB_URL defaults to https://gitlab.com; add it only when you connect to a self-managed GitLab instance.

GITLAB_URL=https://gitlab.example.com

3. Connect your MCP client

Most desktop clients use stdio: the client starts one local MCP server process and talks to it over stdin/stdout. Choose one of these runtime patterns.

Native binary (stdio)

VS Code and Cursor-style MCP configuration:

Add to .vscode/mcp.json in your workspace:

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

Claude Desktop uses the same server command under mcpServers:

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

For client-specific paths, secure token prompts, HTTP OAuth, and extra IDEs, see IDE Configuration.

Docker launched by an IDE (stdio)

If an IDE starts Docker as the MCP server process, keep docker run -i and pass --http=false after the image name. Do not publish port 8080 in this mode.

{
  "servers": {
    "gitlab": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITLAB_TOKEN",
        "-e",
        "GITLAB_URL",
        "-e",
        "GITLAB_SKIP_TLS_VERIFY",
        "ghcr.io/jmrplens/gitlab-mcp-server:latest",
        "--http=false"
      ],
      "env": {
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
        "GITLAB_URL": "https://gitlab.com",
        "GITLAB_SKIP_TLS_VERIFY": "false"
      }
    }
  }
}

Docker or binary as an HTTP MCP server

Use HTTP mode for shared, remote, or multi-user deployments. The Docker image starts in HTTP mode by default, but the flags are shown explicitly here for clarity. These examples publish the container port on host loopback only; --http-addr=0.0.0.0:8080 binds inside the container.

# Fixed GitLab instance for all clients
docker run -d --name gitlab-mcp-server -p 127.0.0.1:8080:8080 \
  ghcr.io/jmrplens/gitlab-mcp-server:latest \
  --http \
  --http-addr=0.0.0.0:8080 \
  --gitlab-url=https://gitlab.com

# Multi-instance mode: clients send GITLAB-URL per request
docker run -d --name gitlab-mcp-server -p 127.0.0.1:8080:8080 \
  ghcr.io/jmrplens/gitlab-mcp-server:latest \
  --http \
  --http-addr=0.0.0.0:8080

HTTP clients authenticate each request with PRIVATE-TOKEN or Authorization: Bearer:

{
  "servers": {
    "gitlab": {
      "type": "http",
      "url": "http://localhost:8080/mcp",
      "headers": {
        "PRIVATE-TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

In multi-instance mode, clients must also send GITLAB-URL. See HTTP Server Mode for OAuth, reverse proxy, rate limit, and server-pool details.

4. Verify

Open your AI client and try:

"List my GitLab projects"

See the Getting Started guide for detailed setup instructions.

Tool Modes

Three registration modes, controlled by META_TOOLS or TOOL_SURFACE:

For dynamic experiments where resources and prompts dominate initial context, set CAPABILITY_SURFACE=minimal (stdio) or --capability-surface=minimal (HTTP) to keep only gitlab://workspace/roots and omit optional MCP resources and prompts. The default remains full.

Meta-tools remain the default today. Dynamic mode is the current low-token candidate for a future default; see Dynamic Toolset for the fuzzy search ranking model, MCP response shapes, search/describe/execute workflow, diagrams, and migration guidance.

Meta-tool summary:

32 base / 47 self-managed enterprise / 48 GitLab.com Enterprise meta-tools. Rows marked 🏢 require the Enterprise/Premium catalog; gitlab_orbit additionally requires GitLab.com. See Meta-Tools Reference for the complete list with actions and examples.

Compatibility

Tested with: VS Code + GitHub Copilot, Claude Desktop, Claude Code, Cursor, Windsurf, JetBrains IDEs, Zed, Kiro, Cline, Roo Code.

See the full Compatibility Matrix for detailed client support.

AI Model Tool-Use Evaluation

The project includes an automated evaluator for model-facing MCP quality. It can run schema-only checks against the tool catalog or execute validated model tool calls through MCP against a Docker GitLab CE instance populated with fixtures. The evaluator measures whether each model chooses the correct meta-tool and action, sends valid parameters, recovers from actionable GitLab errors, and respects destructive-action safeguards.

Current published result: 2026-05-05 Full Docker Economy Run.

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

No Dynamic 2-tool evaluation summary has been published yet.

Current published result: Dynamic 3-tool all-provider Docker run 2026-05-09.

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

Documentation

Full documentation is available at jmrplens.github.io/gitlab-mcp-server.

Tech Stack

Building from Source

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

See the Development Guide for cross-compilation and contributing guidelines.

Container Image

The published image is ghcr.io/jmrplens/gitlab-mcp-server:latest. Runtime examples live in Quick Start next to MCP client configuration, and Docker Compose/source-build details live in the Development Guide.

FAQ

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.

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.

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.

Both Community Edition (CE) and Enterprise Edition (EE). Set GITLAB_ENTERPRISE=true in stdio mode to enable additional tools for Premium/Ultimate features (DORA metrics, vulnerabilities, compliance, etc.). In HTTP mode, --enterprise can force the Enterprise/Premium catalog, otherwise CE/EE is detected per token+URL pool entry when GitLab reports edition.

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.

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.

Contributing

See CONTRIBUTING.md for development guidelines, branch naming, commit conventions, and pull request process.

Security

See SECURITY.md for the security policy and vulnerability reporting.

Code of Conduct

See CODE_OF_CONDUCT.md. This project follows the Contributor Covenant v2.1.

Unnecessary Statistics

Numbers nobody asked for, but here they are anyway.

File counts

Functions

Ratios worth noting

Code patterns

Project

Hall of fame

Because why not