# gitlab-mcp-server > A Model Context Protocol (MCP) server that exposes GitLab REST API v4 and GraphQL operations as tools for AI assistants. gitlab-mcp-server v3.0.0 is a single static binary (Go) that runs locally via stdio or remotely via HTTP transport. It provides up to 1091 individual MCP tools across 98 GitLab API domains, 34 base meta-tools, 51 self-managed enterprise meta-tools, 52 GitLab.com Enterprise meta-tools, a default 2-tool dynamic find/execute surface, 45 resources, 37 prompts, and 4 MCP capabilities (completions, progress, elicitation, resource subscriptions). Cross-platform: Windows, Linux, macOS (amd64 + arm64). Quick start: 1. Install it, or skip installing entirely. Every channel ships the same binary: `npx -y @jmrp.io/gitlab-mcp-server` (npm), `uvx jmrplens-gitlab-mcp-server` (PyPI; `pipx install` and `pip install` take the same name), `dnx gitlab-mcp-server` (NuGet, .NET 10 SDK; `dotnet tool install -g` takes the same name), `brew install jmrplens/tap/gitlab-mcp-server` (Homebrew), `winget install --id jmrplens.gitlab-mcp-server -e` (Windows), the `ghcr.io/jmrplens/gitlab-mcp-server` Docker image, the one-click `gitlab-mcp-server.mcpb` Claude Desktop extension, `/plugin install jmrplens/gitlab-mcp-server` as an Agent Plugin, or a binary from the Releases page. The hosted endpoint at https://mcp.jmrp.io/gitlab installs nothing at all 2. Create a GitLab personal access token with `api` scope. A `read_api` token is also admitted and is served a read-only surface; pair it with `GITLAB_MCP_READ_ONLY=true` when you want that explicitly 3. Add the server to your AI client's MCP configuration with that token in `GITLAB_TOKEN` Installing for an AI assistant: If you are an AI assistant setting this up for a user from just this repository URL, write the MCP client configuration directly; there is no interactive setup to run. The default and recommended surface is dynamic mode over stdio (only two visible tools, lowest token cost). Minimum required: a GitLab personal access token in `GITLAB_TOKEN`; set `GITLAB_URL` only for self-managed instances (default `https://gitlab.com`). The config schema differs by client. Most use a `mcpServers` key: Claude Desktop, Claude Code, Cursor, Windsurf, JetBrains, Kiro, opencode, Cline, Gemini CLI, and the GitLab Duo Agent Platform. VS Code and GitHub Copilot use a `servers` key, with `"type": "stdio"` on each entry. Zed uses `context_servers`, and OpenAI Codex uses TOML `[mcp_servers.gitlab]` in `~/.codex/config.toml`. The `mcpServers` form with Docker: ```json { "mcpServers": { "gitlab": { "command": "docker", "args": ["run", "-i", "--rm", "-e", "GITLAB_TOKEN", "ghcr.io/jmrplens/gitlab-mcp-server:latest"], "env": { "GITLAB_TOKEN": "" } } } } ``` Without Docker: use `npx` as `command` with `args` `["-y", "@jmrp.io/gitlab-mcp-server"]`, `uvx` with `args` `["jmrplens-gitlab-mcp-server"]`, or `dnx` (the .NET 10 SDK's tool runner) with `args` `["gitlab-mcp-server"]`, keeping the same `env`. All three fetch a prebuilt binary for the platform and need no Node, Python or .NET project of their own; arguments meant for the server go after `--` with `dnx`. Native binary instead: download the release asset for the user's OS and architecture (`gitlab-mcp-server--`, with `.exe` on Windows) from the Releases page, then use its path as `command` with no `args` and the same `env`. Claude Code (CLI): the registration command never carries the token. Docker: export `GITLAB_TOKEN` in the shell that launches the client, then `claude mcp add gitlab --transport stdio -- docker run -i --rm -e GITLAB_TOKEN ghcr.io/jmrplens/gitlab-mcp-server:latest`, where `-e GITLAB_TOKEN` with no value forwards the variable from the environment Claude Code hands `docker`. Native binary: write `GITLAB_TOKEN=` to `~/.gitlab-mcp-server.env`, which the server reads for values its environment does not already carry, then `claude mcp add gitlab -- gitlab-mcp-server`. Do not suggest `--env GITLAB_TOKEN=`: a shell expands before exec, so the value lands in the process arguments either way, and `claude mcp add` persists whatever it is given into its own configuration file. One Docker caveat, for images tagged v2.7.5 or earlier only: those default to HTTP and hang at `initialize` when a client speaks stdio to them. Append `--http=false` after the image name for such a tag. Later images infer the transport from stdin, so `docker run -i` is enough and no extra argument is needed. Nothing installed at all: https://mcp.jmrp.io/gitlab is a public instance of this server, fixed to https://gitlab.com and serving the default dynamic surface over stateless streamable HTTP. An OAuth-capable client needs no header and discovers the authorization server from the RFC 9728 challenge; any other client sends a GitLab.com token as `Authorization: Bearer `, verified per request and never stored. It is one person's personal service with no SLA, so deploy your own for anything that matters. The exact config-file path and JSON schema for each client (VS Code with GitHub Copilot, Claude Code, Claude Desktop, Cursor, OpenAI Codex CLI, Gemini CLI, LM Studio, mcp-remote, GitLab Duo Agent Platform, Windsurf, JetBrains, Zed, Kiro, opencode, Cline; stdio / HTTP / OAuth) are in [docs/guides/ide-configuration.md](https://github.com/jmrplens/gitlab-mcp-server/blob/main/docs/guides/ide-configuration.md). Running the binary by hand: - Without both `GITLAB_URL` and `GITLAB_TOKEN`, and with a terminal attached, the server prints what it needs on stderr and waits for Enter rather than starting a session it cannot serve. An MCP client never reaches that screen, because a client connects pipes rather than a terminal. - Keeping the token out of client config: put `GITLAB_URL` and `GITLAB_TOKEN` in `~/.gitlab-mcp-server.env`, or in the one file `GITLAB_MCP_ENV_FILE` names (give it an absolute path). Precedence, highest first: the process environment, then `GITLAB_MCP_ENV_FILE`, then the home file. A `.env` in the working directory is deliberately not loaded, only reported at WARN with the keys it wanted to set. - Updating: use whichever channel installed it. The server never replaces its own binary. Configuration (environment variables, stdio mode). Settings this project defines are read as GITLAB_MCP_; the older bare spellings still work and warn once at startup: - GITLAB_URL: GitLab instance URL (default: `https://gitlab.com`; set for self-managed instances) - GITLAB_TOKEN: Personal Access Token (required) - GITLAB_MCP_SKIP_TLS_VERIFY: Skip TLS verification for self-signed certs (default: false) - GITLAB_MCP_TOOL_SURFACE: Canonical catalog selector: dynamic (default), meta, individual - GITLAB_MCP_CAPABILITY_SURFACE: Use minimal with dynamic mode when startup context must be tiny (minimal also drops resource subscriptions) - GITLAB_MCP_READ_ONLY: Remove mutating operations per action; reads keep working (default: false) - GITLAB_MCP_SAFE_MODE: Answer a mutating action with a JSON preview naming it instead of running it; reads keep working (default: false). GITLAB_MCP_READ_ONLY takes precedence - GITLAB_MCP_TIER: Licensing tier (free/ce, premium, ultimate); unset detects from the instance license (fallback free). Premium/Ultimate enable enterprise tools; GitLab.com Enterprise also exposes Orbit Knowledge Graph tools - GITLAB_MCP_LOG_LEVEL: debug, info (default), warn, error. Logs go to stderr; stdout carries nothing but JSON-RPC - GITLAB_MCP_ENV_FILE: One dotenv file to load besides `~/.gitlab-mcp-server.env`; give an absolute path - GITLAB_MCP_META_TOOLS: Deprecated compatibility selector; prefer GITLAB_MCP_TOOL_SURFACE for new configs Tool domains: Access, Achievement, Admin, Branch, CI Catalog, CI Variable, Custom Emoji, Discover Project, Environment, Feature Flags, Group, Interactive Issue Create, Interactive MR Create, Interactive Project Create, Interactive Release Create, Issue, Job, MR Review, Merge Request, Model Registry, Package, Pipeline, Project, Release, Repository, Runner, Search, Server, Snippet, Storage Move, Tag, Template, User, Wiki. Dynamic toolset (default mode): When GITLAB_MCP_TOOL_SURFACE is unset or set to dynamic, the server exposes only gitlab_find_action and gitlab_execute_action while keeping the same canonical GitLab action catalog. Models should find an action with its exact schema, then execute the canonical domain.action ID returned by find. Set GITLAB_MCP_TOOL_SURFACE=meta to use consolidated domain meta-tools instead. - gitlab_find_action: Search the local GitLab action catalog. - gitlab_execute_action: Execute one GitLab catalog action by canonical ID or alias. Meta-tool overview: When GITLAB_MCP_TOOL_SURFACE=meta, 34 domain meta-tools are registered instead of up to 1091 individual tools. Enterprise/Premium entries register 51 meta-tools on self-managed GitLab, or 52 on GitLab.com when Orbit is available. Each meta-tool groups related operations under a single tool with an "action" parameter. Key meta-tools: - gitlab_access: Manage GitLab access credentials: access tokens (project/group/personal), deploy... - gitlab_achievement: GitLab achievement actions. - gitlab_admin: GitLab self-managed instance administration: settings, license, broadcast messag... - gitlab_branch: Manage Git branches and branch protections in a project, plus aggregated branch ... - gitlab_ci_catalog: Discover and inspect CI/CD Catalog resources (reusable pipeline components and t... - gitlab_ci_variable: Manage GitLab CI/CD variables at instance, group, and project scope. - gitlab_custom_emoji: Manage group-level custom emoji via GraphQL. - gitlab_discover_project: Resolve a full git remote URL to a GitLab project and return its project_id and ... - gitlab_environment: Manage GitLab deployment environments, protected environments, freeze (deploy bl... - gitlab_feature_flags: Manage project feature flags and feature-flag user lists for gradual rollouts. - gitlab_group: Manage GitLab groups: CRUD, subgroups, members, labels, milestones, webhooks, ba... - gitlab_interactive_issue_create: Create a GitLab issue through step-by-step prompts, with explicit confirmation b... - gitlab_interactive_mr_create: Create a GitLab merge request through step-by-step prompts, with explicit confir... - gitlab_interactive_project_create: Create a GitLab project through step-by-step prompts, with explicit confirmation... - gitlab_interactive_release_create: Create a GitLab release through step-by-step prompts, with explicit confirmation... - gitlab_issue: Manage GitLab issues: CRUD, notes, discussions, links, time tracking, work items... - gitlab_job: Manage GitLab CI/CD jobs and the CI/CD job token scope: lifecycle, manual play, ... - gitlab_merge_request: Manage GitLab merge request lifecycle plus approval rules and settings, time tra... - gitlab_model_registry: Download ML model package files from the GitLab Model Registry. - gitlab_mr_review: Review and comment on GitLab merge requests: notes, threaded discussions (inline... - gitlab_package: Manage GitLab package registry, container registry, and protection rules. - gitlab_pipeline: Manage GitLab CI/CD pipelines plus trigger tokens, resource groups (mutual-exclu... - gitlab_project: Manage GitLab projects end-to-end: lifecycle (create/fork/transfer/archive/delet... - gitlab_release: Manage GitLab releases and their asset links (binaries, packages, runbooks). - gitlab_repository: Browse and manage GitLab repository content: file tree, read/write/delete files,... - gitlab_runner: Manage GitLab CI/CD runners (instance, group, project) and runner controllers (a... - gitlab_search: Search GitLab by scope (instance / group / project) for code, MRs, issues, commi... - gitlab_server: MCP server self-diagnostics: GitLab connectivity probe, server/GitLab version, a... - gitlab_snippet: Manage GitLab snippets (personal, project-scoped, and explore feed): CRUD snippe... - gitlab_storage_move: Manage repository storage moves for projects, groups, and snippets (admin only). - gitlab_tag: Manage Git tags and tag protections in a project, plus GPG signature inspection. - gitlab_template: Browse GitLab built-in templates (gitignore, CI/CD YAML, Dockerfile, license, pr... - gitlab_user: User management for GitLab: full user account CRUD plus SSH/GPG keys, emails, pe... - gitlab_wiki: CRUD project wiki pages and upload attachments to wikis. Resources: 45 read-only resources (26 resource kinds are subscribable, subscriptions/listen on protocol 2026-07-28, resources/subscribe on stateful sessions; change detection honored by polling): - gitlab://groups: groups - gitlab://guides/code-review: code_review - gitlab://guides/conventional-commits: conventional_commits - gitlab://guides/git-workflow: git_workflow - gitlab://guides/merge-request-hygiene: merge_request_hygiene - gitlab://guides/pipeline-troubleshooting: pipeline_troubleshooting - gitlab://tools: tool_manifest - gitlab://user/current: current_user - gitlab://group/{group_id}: group - gitlab://group/{group_id}/label/{label_id}: group_label - gitlab://group/{group_id}/members: group_members - gitlab://group/{group_id}/milestone/{milestone_iid}: group_milestone - gitlab://group/{group_id}/projects: group_projects - gitlab://project/{project_id}: project - gitlab://project/{project_id}/board/{board_id}: board - gitlab://project/{project_id}/branch/{branch}: branch - gitlab://project/{project_id}/branches: project_branches - gitlab://project/{project_id}/commit/{sha}: commit - gitlab://project/{project_id}/deploy_key/{deploy_key_id}: deploy_key - gitlab://project/{project_id}/deployment/{deployment_id}: deployment - gitlab://project/{project_id}/environment/{environment_id}: environment - gitlab://project/{project_id}/feature_flag/{name}: feature_flag - gitlab://project/{project_id}/file/{ref}/{+path}: file_blob - gitlab://project/{project_id}/issue/{issue_iid}: issue - gitlab://project/{project_id}/issues: project_issues - gitlab://project/{project_id}/job/{job_id}: job - gitlab://project/{project_id}/label/{label_id}: label - gitlab://project/{project_id}/labels: project_labels - gitlab://project/{project_id}/members: project_members - gitlab://project/{project_id}/milestone/{milestone_iid}: milestone - gitlab://project/{project_id}/milestones: project_milestones - gitlab://project/{project_id}/mr/{merge_request_iid}: merge_request - gitlab://project/{project_id}/mr/{merge_request_iid}/discussions: merge_request_discussions - gitlab://project/{project_id}/mr/{merge_request_iid}/notes: merge_request_notes - gitlab://project/{project_id}/pipeline/{pipeline_id}: pipeline - gitlab://project/{project_id}/pipeline/{pipeline_id}/jobs: pipeline_jobs - gitlab://project/{project_id}/pipelines/latest: latest_pipeline - gitlab://project/{project_id}/release/{tag_name}: release - gitlab://project/{project_id}/releases: project_releases - gitlab://project/{project_id}/snippet/{snippet_id}: project_snippet - gitlab://project/{project_id}/tag/{tag_name}: tag - gitlab://project/{project_id}/tags: project_tags - gitlab://project/{project_id}/wiki/{slug}: wiki_page - gitlab://snippet/{snippet_id}: snippet - gitlab://tools/{id}: tool_detail Prompts: 37 prompts: - audit_commit_hygiene: Audit commit message quality between two refs. - audit_project_full: Run a comprehensive audit of a GitLab project covering settings, branch protecti... - audit_project_workflow: Audit workflow configuration for a GitLab project: labels (names, colors, descri... - branch_mr_summary: List all MRs targeting a specific branch in a project. - compare_branches: Compare commit and file differences between two Git refs. - daily_standup: Generate a daily standup summary based on the user's GitLab activity in the last... - generate_release_notes: Generate comprehensive release notes from commits, merge requests, and file chan... - group_milestone_progress: Track milestone progress across all projects in a group. - group_mr_dashboard: List merge requests across a GitLab group with optional state and target branch ... - label_distribution: Analyze label usage distribution in a project. - merge_velocity: Analyze MR throughput metrics for a project. - milestone_progress: Track milestone progress for a project. - mr_description_quality: Score a merge request description for reviewer readiness. - mr_discussion_health: Analyze unresolved discussion threads across open MRs in a project. - mr_risk_assessment: Assess the risk level (LOW/MEDIUM/HIGH/CRITICAL) of a merge request based on siz... - my_activity_summary: Generate a personal activity summary for a configurable time period. - my_issues: Show all issues assigned to you across all projects. - my_open_mrs: Show all open merge requests across all projects where you are author or assigne... - my_pending_reviews: Show all open merge requests where you are assigned as reviewer across all proje... - project_activity_report: Generate a project activity report including recent events, merged MRs, and open... - project_contributors: Rank project contributors by commits, additions, and deletions. - project_health_check: Comprehensive project health assessment combining latest pipeline status, open m... - release_cadence: Analyze release frequency for a project. - release_readiness: Check readiness of a release branch by analyzing open MRs targeting it, draft/co... - review_mr: Generate a structured code review for a merge request. Files are categorized by ... - reviewer_workload: Analyze review distribution across group members. - stale_items_report: Find MRs and issues in a project that haven't been updated for a configurable nu... - suggest_mr_reviewers: Suggest suitable merge request reviewers based on the files changed and the list... - summarize_mr_changes: Summarize the changed files and key modifications in a merge request. Lists each... - summarize_open_mrs: Summarize all open merge requests in a project including title, author, branches... - summarize_pipeline_status: Summarize the latest CI/CD pipeline status for a project. - team_member_workload: Generate a comprehensive workload summary for a specific team member over a conf... - team_overview: Generate a team dashboard showing all group members with their open MR counts an... - unassigned_items: Find open MRs and issues in a project that have no assignee. - user_activity_report: Generate a detailed activity report for a specific user: contribution events, me... - user_stats: Generate comprehensive user statistics from GitLab: contribution events breakdow... - weekly_team_recap: Generate a comprehensive weekly recap for a team. ## Documentation - [Documentation site index](https://jmrp.io/docs/gitlab-mcp-server/llms.txt): Index of every published documentation page, which is what the documentation domain serves at /llms.txt - [Spanish documentation index](https://jmrp.io/docs/gitlab-mcp-server/es/llms.txt): The same documentation in Spanish, page for page - [Getting started](https://github.com/jmrplens/gitlab-mcp-server/blob/main/docs/getting-started.md): Installation and first-run guide - [Installation](https://github.com/jmrplens/gitlab-mcp-server/blob/main/docs/guides/installation.md): Every install channel with its exact command, and how each one upgrades - [Claude Desktop extension](https://github.com/jmrplens/gitlab-mcp-server/blob/main/docs/guides/claude-desktop-extension.md): One-click .mcpb install for Claude Desktop (macOS universal + Windows) - [Configuration](https://github.com/jmrplens/gitlab-mcp-server/blob/main/docs/reference/configuration.md): Full configuration reference - [Environment variables](https://github.com/jmrplens/gitlab-mcp-server/blob/main/docs/reference/env.md): Environment variable reference - [HTTP server mode](https://github.com/jmrplens/gitlab-mcp-server/blob/main/docs/guides/http-server-mode.md): Remote MCP transport setup - [Security model](https://github.com/jmrplens/gitlab-mcp-server/blob/main/docs/concepts/security.md): Authentication, read-only mode, safe mode, and security controls - [Resource subscriptions](https://github.com/jmrplens/gitlab-mcp-server/blob/main/docs/reference/capabilities/subscriptions.md): resources/subscribe by polling: 26 subscribable kinds, cadence, lifetime, limits - [Privacy policy](https://github.com/jmrplens/gitlab-mcp-server/blob/main/PRIVACY.md): No telemetry; data flows only to the configured GitLab instance ## Tool References - [Dynamic tools](https://github.com/jmrplens/gitlab-mcp-server/blob/main/docs/concepts/dynamic-tools.md): Low-token find/execute mode and usage pattern - [Meta-tools](https://github.com/jmrplens/gitlab-mcp-server/blob/main/docs/concepts/meta-tools.md): Consolidated domain meta-tool action reference - [All tools](https://github.com/jmrplens/gitlab-mcp-server/blob/main/docs/reference/tools/README.md): Complete per-domain tool reference - [Resources](https://github.com/jmrplens/gitlab-mcp-server/blob/main/docs/reference/resources.md): Read-only MCP resource reference - [Prompts](https://github.com/jmrplens/gitlab-mcp-server/blob/main/docs/reference/prompts.md): Reusable MCP prompt templates ## Optional - [Medium LLM reference](https://jmrp.io/docs/gitlab-mcp-server/llms-medium.txt): 153 KB, ~39k tokens. Every tool and action with its description, without the per-action JSON schemas. The largest of these that still loads into a context window - [Meta-tools reference](https://jmrp.io/docs/gitlab-mcp-server/llms-full-meta-tools.txt): 2.2 MB, ~588k tokens. Full schemas for the dynamic and meta-tool surfaces only - [Individual tools reference](https://jmrp.io/docs/gitlab-mcp-server/llms-full-individual-tools.txt): 894 KB, ~229k tokens. Full schemas for the one-tool-per-operation surface only - [Resources and prompts reference](https://jmrp.io/docs/gitlab-mcp-server/llms-full-resources-prompts.txt): 29 KB, ~7k tokens. MCP resource and prompt definitions only - [Full LLM reference](https://jmrp.io/docs/gitlab-mcp-server/llms-full.txt): 3.1 MB, ~824k tokens. The three splits above concatenated. Past every current context window, so search or retrieve inside it rather than loading it; if you want one surface, take its split instead - [Architecture](https://github.com/jmrplens/gitlab-mcp-server/blob/main/docs/concepts/architecture.md): Internal architecture and catalog-first runtime overview - [Output format](https://github.com/jmrplens/gitlab-mcp-server/blob/main/docs/reference/output-format.md): Markdown and structured output conventions - [Troubleshooting](https://github.com/jmrplens/gitlab-mcp-server/blob/main/docs/guides/troubleshooting.md): Common setup and runtime issues - [Evaluation results](https://github.com/jmrplens/gitlab-mcp-server/blob/main/docs/development/testing/model-results.md): Surface evaluation summaries for model behavior