# 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 v2.0.3 is a single static binary (Go) that runs locally via stdio or remotely via HTTP transport.
It provides up to 1023 individual MCP tools across 98 GitLab API domains, 33 base meta-tools, 49 self-managed enterprise meta-tools, 50 GitLab.com Enterprise meta-tools,
a default 2-tool dynamic find/execute surface, 46 resources, 37 prompts, and 6 MCP capabilities. Cross-platform: Windows, Linux, macOS (amd64 + arm64).

Quick start:

1. Download the binary for your platform from the Releases page
2. Run `gitlab-mcp-server --setup` to launch the interactive setup wizard
3. The wizard configures your AI client (VS Code, Cursor, Claude Desktop, etc.)

Configuration (environment variables, stdio mode):

- GITLAB_URL: GitLab instance URL (default: `https://gitlab.com`; set for self-managed instances)
- GITLAB_TOKEN: Personal Access Token (required)
- GITLAB_SKIP_TLS_VERIFY: Skip TLS verification for self-signed certs (default: false)
- TOOL_SURFACE: Canonical catalog selector: meta, individual, dynamic
- META_TOOLS: Deprecated compatibility selector; prefer TOOL_SURFACE for new configs
- CAPABILITY_SURFACE: Use minimal with dynamic mode when startup context must be tiny
- GITLAB_ENTERPRISE: Enable enterprise/premium tools; GitLab.com Enterprise also exposes Orbit Knowledge Graph tools (default: false)

Tool domains:

Access, Admin, Analyze, 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, Snippet, Storage Move, Tag, Template, User, Wiki.

Dynamic toolset (default mode):

When TOOL_SURFACE is unset or set to dynamic, the server exposes only gitlab_find_action and gitlab_execute_tool 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 TOOL_SURFACE=meta to use consolidated domain meta-tools instead.

- gitlab_find_action: Search the local GitLab action catalog; read-only and no GitLab API call.
- gitlab_execute_tool: Execute one GitLab catalog action by canonical ID or alias.

Meta-tool overview:

When TOOL_SURFACE=meta, 33 domain meta-tools are registered instead of
up to 1023 individual tools. Enterprise/Premium entries register 49 meta-tools on self-managed GitLab,
or 50 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_admin: GitLab self-managed instance administration: settings, license, broadcast messag...
- gitlab_analyze: LLM-assisted analysis of GitLab data via MCP sampling.
- 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_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:

46 read-only resources:

- 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
- gitlab://workspace/roots: Workspace Roots

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

- [Getting started](docs/getting-started.md): Installation and first-run guide
- [Configuration](docs/configuration.md): Full configuration reference
- [Environment variables](docs/env-reference.md): Environment variable reference
- [HTTP server mode](docs/http-server-mode.md): Remote MCP transport setup
- [Security model](docs/security.md): Authentication, read-only mode, safe mode, and security controls

## Tool References

- [Dynamic tools](docs/dynamic-tools.md): Low-token find/execute mode and usage pattern
- [Meta-tools](docs/meta-tools.md): Consolidated domain meta-tool action reference
- [All tools](docs/tools/README.md): Complete per-domain tool reference
- [Resources](docs/resources-reference.md): Read-only MCP resource reference
- [Prompts](docs/prompts-reference.md): Reusable MCP prompt templates

## Optional

- [Full LLM reference](llms-full.txt): Generated companion reference with tool schemas, resource listings, and prompts
- [Architecture](docs/architecture.md): Internal architecture and catalog-first runtime overview
- [Output format](docs/output-format.md): Markdown and structured output conventions
- [Troubleshooting](docs/troubleshooting.md): Common setup and runtime issues
- [Evaluation results](docs/testing/model-results.md): Surface evaluation summaries for model behavior
