# Gitlab Mcp Server > Open source GitLab MCP server for AI assistants: 2-tool dynamic find/execute over 860+ GitLab actions (1,000+ Enterprise), stdio/HTTP/OAuth, safe/read-only modes. - **Type:** MCP server - **Install:** `agentstack add mcp-jmrplens-gitlab-mcp-server` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [jmrplens](https://agentstack.voostack.com/s/jmrplens) - **Installs:** 0 - **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [jmrplens](https://github.com/jmrplens) - **Source:** https://github.com/jmrplens/gitlab-mcp-server - **Website:** https://jmrplens.github.io/gitlab-mcp-server/ ## Install ```sh agentstack add mcp-jmrplens-gitlab-mcp-server ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # GitLab MCP Server [](https://github.com/jmrplens/gitlab-mcp-server/releases/latest) [](LICENSE) [](https://goreportcard.com/report/github.com/jmrplens/gitlab-mcp-server) [](https://pkg.go.dev/github.com/jmrplens/gitlab-mcp-server/v2) [](https://glama.ai/mcp/servers/jmrplens/gitlab-mcp-server) [](https://gitlab.com/jmrp/gitlab-mcp-server) [](https://sonarcloud.io/summary/overall?id=jmrplens_gitlab-mcp-server) [](https://sonarcloud.io/summary/overall?id=jmrplens_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](https://sonarcloud.io/summary/overall?id=jmrplens_gitlab-mcp-server) with quality gates, coverage, and security scanning. Supports read-only mode, safe mode (dry-run preview), and self-hosted GitLab with TLS verification. > > **Repository mirror**: GitHub is the canonical repository. A read-only mirror of the code and releases is available on [GitLab.com](https://gitlab.com/jmrp/gitlab-mcp-server) for discoverability; please open code contributions on GitHub. ## Token Footprint Measured with `go run ./cmd/gen_readme/` against the current base catalog. Totals estimate startup context visible to an MCP client: visible tool schemas plus shared resources and prompts, using the same byte/4 token heuristic as `cmd/audit_tokens`. **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`) | Visible tools | Reachable actions | `META_PARAM_SCHEMA` | Tool schema tokens | Shared tokens | Total tokens | | ----------------------------------------------------- | ------------: | ----------------: | ------------------- | -----------------: | ------------: | -----------: | | `dynamic` / `full` (default) | 2 | 864 | n/a | 2,204 | 18,100 | 20,304 | | `dynamic` / `minimal` | 2 | 864 | n/a | 2,204 | 555 | 2,759 | | `meta` / `full` | 33 | 864 | `opaque` | 144,458 | 18,100 | 162,558 | | `meta` / `minimal` | 33 | 864 | `opaque` | 144,458 | 555 | 145,013 | | `individual` / `full` | 860 | 860 | n/a | 678,524 | 18,100 | 696,624 | Rows use the base Community Edition catalog (`GITLAB_TIER=free`). `META_PARAM_SCHEMA=opaque` affects only visible meta-tool input schemas; dynamic mode gets exact action schemas from `gitlab_find_action`, and every surface advertises `gitlab://tools` plus `gitlab://tools/{id}` for on-demand action browsing and input schemas. Individual mode already exposes one schema per tool. ## Highlights - **1061 MCP tools** on self-managed Enterprise/Premium, or **1067 on GitLab.com Enterprise/Premium** with experimental Orbit Knowledge Graph support — broad GitLab REST API v4 + GraphQL coverage across 175 packages under `internal/tools`: projects, branches, tags, releases, merge requests, issues, pipelines, jobs, groups, users, wikis, environments, deployments, packages, container registry, runners, feature flags, CI/CD variables, security attributes, security categories, templates, admin settings, access tokens, deploy keys, Orbit, and more - **Default dynamic toolset** — exposes only `gitlab_find_action` and `gitlab_execute_action` while keeping the same canonical GitLab action catalog. Optional domain meta-tools remain available with `TOOL_SURFACE=meta`: 32 base, 48 on self-managed Enterprise/Premium, or 49 on GitLab.com Enterprise/Premium - **AI model tool-use evaluation** — automated schema-only and Docker-backed runs against populated GitLab CE and licensed Enterprise instances measure tool/action selection, parameter shaping, recovery from GitLab errors, and destructive-action safety across Anthropic, Google, OpenAI, and Qwen. Published summaries appear in the managed evaluation block below; see [AI Model Evaluation Results](docs/testing/model-results.md) - **4 elicitation tools** — interactive creation wizards (issue, MR, release, project) with step-by-step user prompts - **45 MCP resources** in default dynamic/full mode — 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, 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), the surface-aware `gitlab://tools` manifest and `gitlab://tools/{id}` detail template, and 5 workflow best-practice guides - **37 MCP prompts** — AI-optimized: code review, pipeline status, risk assessment, release notes, standup, workload, user stats, team management, cross-project dashboards, analytics, milestones, Git workflow quality, audit - **3 MCP capabilities** — completions, progress, 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](docs/examples/usage-examples.md) for more scenarios. ## Quick Start ### 1. Get the server Download the latest binary for your platform from [GitHub Releases](https://github.com/jmrplens/gitlab-mcp-server/releases) and make it executable: ```bash chmod +x gitlab-mcp-server-* # Linux/macOS only ``` Or pull the published container image: ```bash 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: ```bash ./gitlab-mcp-server --setup ``` > **Tip**: The wizard supports three user interfaces and selects the best one automatically (Web UI → TUI → CLI). Force a specific mode with `--setup-mode web|tui|cli`. The Web UI ships with inline help tooltips on every advanced option. On Windows, double-click the `.exe` to launch the wizard automatically. The wizard configures **stdio MCP clients** (VS Code, Claude Desktop, Cursor, etc.). It is not used for the long-running HTTP server mode — see [HTTP Server Mode](docs/http-server-mode.md) for that. If `~/.gitlab-mcp-server.env` already exists, the wizard pre-loads its values so you can re-run it to change just one or two fields without re-typing the rest. Leave the token field blank to keep the stored token. Manual setup only needs a GitLab Personal Access Token with `api` scope: ```env GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx ``` `GITLAB_URL` defaults to `https://gitlab.com`; add it only when you connect to a self-managed GitLab instance. ```env 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: ```json { "servers": { "gitlab": { "type": "stdio", "command": "/path/to/gitlab-mcp-server", "env": { "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx" } } } } ``` Claude Desktop uses the same server command under `mcpServers`: ```json { "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](docs/ide-configuration.md). #### 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. ```json { "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. ```bash # 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`: ```jsonc { "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](docs/http-server-mode.md) 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](https://jmrplens.github.io/gitlab-mcp-server/getting-started/) for detailed setup instructions. ## Tool Modes Three registration modes, controlled by `TOOL_SURFACE`: | Mode | Tools | Description | | ----------------------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Dynamic Toolset** (default) | 2 visible tools | Low-token find/execute surface over the canonical action catalog. | | **Meta-Tools** | 32 base GitLab/interactive tools; `gitlab_server` is a separate maintenance helper | Domain-grouped dispatchers with `action` parameter. Enable with `TOOL_SURFACE=meta`; see the full 32/48/49 catalog in [Meta-Tools Reference](docs/meta-tools.md). | | **Individual** | 893 CE / 1061 self-managed enterprise / 1067 GitLab.com Enterprise | Every GitLab operation as a separate MCP tool. | For dynamic experiments where resources and prompts dominate initial context, set `CAPABILITY_SURFACE=minimal` (stdio) or `--capability-surface=minimal` (HTTP). Minimal keeps the surface-aware `gitlab://tools` manifest so dynamic, meta, and individual deployments can still read accepted call shapes. The default remains `full`. Dynamic mode is now the default low-token find/execute surface; see [Dynamic Toolset](docs/dynamic-tools.md) for the field-aware ranking model, fuzzy fallback, response shapes, workflow diagrams, and migration guidance. Set `TOOL_SURFACE=meta` to use the consolidated domain meta-tool catalog. The detailed meta-tool catalog now lives in [Meta-Tools Reference](docs/meta-tools.md), including action counts, Enterprise/Premium markers, and examples. ## Compatibility | MCP Capability | Support | | --------------- | ---------------------------------- | | **Tools** | Up to 1067 individual / 32–49 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, Roo Code. See the full [Compatibility Matrix](https://jmrplens.github.io/gitlab-mcp-server/compatibility/) 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 Docker GitLab CE or licensed Enterprise instances 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: **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 ca … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [jmrplens](https://github.com/jmrplens) - **Source:** [jmrplens/gitlab-mcp-server](https://github.com/jmrplens/gitlab-mcp-server) - **License:** MIT - **Homepage:** https://jmrplens.github.io/gitlab-mcp-server/ Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-jmrplens-gitlab-mcp-server - Seller: https://agentstack.voostack.com/s/jmrplens - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.