# 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.2.0 is a single self-contained binary (Go, no runtime to install) that runs locally via stdio or remotely via HTTP transport. It provides up to 1094 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 the actions GitLab accepts from `read_api`, a few of which write; pair it with `GITLAB_MCP_READ_ONLY=true` for a session that writes nothing 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, Cline, Gemini CLI, LM Studio, and the GitLab Duo Agent Platform. VS Code and GitHub Copilot use a `servers` key, with `"type": "stdio"` on each entry. OpenCode uses `mcp` in `opencode.json`, where each entry carries `"type": "local"`, takes `command` as an array holding the program and its arguments, and names its variables `environment` rather than `env`. 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 entry 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, Continue; stdio / HTTP / OAuth) are on [the MCP clients page](https://docs.jmrp.io/gitlab-mcp-server/install/clients/). 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_ and under no other spelling; the older bare spellings were removed in 3.1.0, and one still set is named at startup, where GITLAB_READ_ONLY, GITLAB_SAFE_MODE and EXCLUDE_TOOLS refuse the start: - 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 it from the instance license, then from the plans of the namespaces the token administers, then on GitLab.com from the plans of the top-level groups the token is a member of, falling back to 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 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 1094 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: Audit a GitLab project in one report: a quick scorecard, then settings, branch p... - audit_project_workflow: Audit workflow configuration for a GitLab project: labels (names, colors, descri... - branch_mr_summary: List up to 100 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 for a user: contribution events of the last 24 ... - generate_release_notes: Generate release notes from the commits, file changes, and merge requests betwee... - group_milestone_progress: Track the progress of up to 100 active group milestones across the group's proje... - group_mr_dashboard: List up to 100 merge requests across a GitLab group with optional state and targ... - label_distribution: Analyze label usage distribution in a project from up to 100 labels. - merge_velocity: Analyze MR throughput for a project from up to 100 MRs created in the period and... - 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 up to 20 open MRs in a project, the... - mr_risk_assessment: Assess the risk level (LOW/MEDIUM/HIGH/CRITICAL) of a merge request from up to 1... - my_activity_summary: Generate a personal activity summary for a configurable period, across all proje... - my_issues: Show up to 100 issues assigned to you across all projects. - my_open_mrs: Show the open merge requests across all projects where you are author or assigne... - my_pending_reviews: Show up to 100 open merge requests across all projects where you are assigned as... - project_activity_report: Generate a project activity report: the counts of events, open MRs, open issues ... - project_contributors: Rank up to 100 project contributors by commits, additions, and deletions. - project_health_check: Project health assessment combining the latest pipeline of the default branch (t... - release_cadence: Analyze release frequency for a project from its up to 100 most recent releases. - release_readiness: Check readiness of a release branch from up to 100 open MRs targeting it: draft/... - review_mr: Generate a structured code review for a merge request, reading up to 100 changed... - reviewer_workload: Analyze review distribution across up to 100 direct members of a group, from up ... - stale_items_report: Find up to 100 open MRs and 100 open issues in a project that haven't been updat... - suggest_mr_reviewers: Suggest suitable merge request reviewers based on up to 100 changed files and th... - summarize_mr_changes: Summarize the changed files and key modifications in a merge request, reading up... - summarize_open_mrs: Summarize up to 100 open merge requests in a project, the most recently created ... - summarize_pipeline_status: Summarize the latest CI/CD pipeline of a project's default branch, or the newest... - team_member_workload: Generate a workload summary for a team member over a configurable period: contri... - team_overview: Generate a team dashboard of up to 100 direct members of a group, each with the ... - unassigned_items: Find up to 100 open MRs and 100 open issues in a project that have no assignee. - user_activity_report: Generate an activity report for a user: contribution events, MRs they authored t... - user_stats: Generate statistics for a user: contribution events across all projects with the... - weekly_team_recap: Generate a weekly recap for a team: MRs created in the period and merged, by pro... ## Documentation - [Documentation site index](https://docs.jmrp.io/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://docs.jmrp.io/gitlab-mcp-server/es/llms.txt): The same documentation in Spanish, page for page - [Getting started](https://docs.jmrp.io/gitlab-mcp-server/getting-started/): Installation and first-run guide - [Installation](https://docs.jmrp.io/gitlab-mcp-server/install/overview/): Every install channel with its exact command, and how each one upgrades - [MCP clients](https://docs.jmrp.io/gitlab-mcp-server/install/clients/): Config-file path and entry for each MCP client, over stdio, HTTP and OAuth - [Claude Desktop extension](https://docs.jmrp.io/gitlab-mcp-server/claude-desktop/): One-click .mcpb install for Claude Desktop (macOS universal, Windows x64, Linux x64 and arm64) - [Configuration](https://docs.jmrp.io/gitlab-mcp-server/configuration/): Full configuration reference - [Environment variables](https://docs.jmrp.io/gitlab-mcp-server/reference/environment/): Environment variable reference - [HTTP server mode](https://docs.jmrp.io/gitlab-mcp-server/operations/http-server/): Remote MCP transport setup - [Security model](https://docs.jmrp.io/gitlab-mcp-server/operations/security/): Authentication, read-only mode, safe mode, and security controls - [Resource subscriptions](https://docs.jmrp.io/gitlab-mcp-server/capabilities/subscriptions/): 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://docs.jmrp.io/gitlab-mcp-server/tools/dynamic-tools/): Low-token find/execute mode and usage pattern - [Meta-tools](https://docs.jmrp.io/gitlab-mcp-server/tools/meta-tools/): Consolidated domain meta-tool action reference - [All tools](https://docs.jmrp.io/gitlab-mcp-server/reference/tools/): Per-domain tool reference generated from the action catalog, one page per catalog group - [Resources](https://docs.jmrp.io/gitlab-mcp-server/tools/resources-prompts/#what-are-mcp-resources): Read-only MCP resource reference - [Prompts](https://docs.jmrp.io/gitlab-mcp-server/tools/resources-prompts/#what-are-mcp-prompts): Reusable MCP prompt templates ## Optional - [Medium LLM reference](https://docs.jmrp.io/gitlab-mcp-server/llms-medium.txt): 157 KB, ~40k 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://docs.jmrp.io/gitlab-mcp-server/llms-full-meta-tools.txt): 2.3 MB, ~615k tokens. Full schemas for the dynamic and meta-tool surfaces only - [Individual tools reference](https://docs.jmrp.io/gitlab-mcp-server/llms-full-individual-tools.txt): 983 KB, ~252k tokens. Full schemas for the one-tool-per-operation surface only - [Resources and prompts reference](https://docs.jmrp.io/gitlab-mcp-server/llms-full-resources-prompts.txt): 32 KB, ~8k tokens. MCP resource and prompt definitions only - [Full LLM reference](https://docs.jmrp.io/gitlab-mcp-server/llms-full.txt): 3.3 MB, ~875k 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://docs.jmrp.io/gitlab-mcp-server/architecture/): Internal architecture and catalog-first runtime overview - [Output format](https://docs.jmrp.io/gitlab-mcp-server/reference/output-format/): Markdown and structured output conventions - [Troubleshooting](https://docs.jmrp.io/gitlab-mcp-server/operations/troubleshooting/): 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