GitLab MCP Server

GitLab MCP Server (@sumirati/mcp-gitlab)

A modern, 2026 AI-native Model Context Protocol (MCP) server for GitLab API v4, engineered for self-hosted GitLab Community Edition (CE), Enterprise Edition (EE), and GitLab.com.

What makes v3.0.0 Unique: The 2026 5-Tool Hybrid Standard

In early MCP servers, dumping 50–100 tools into the client's tool list consumed 10,000+ prompt context tokens on every turn ("System Prompt Tax") and resulted in poor Coherence ratings on the [Glama TDQS](https://github.com/glama-ai/tool-definition-quality-score) rubric.

@sumirati/mcp-gitlab v3 solves this with a 5-Tool Hybrid Surface:

• Glama TDQS Coherence Tier A (5/5): By exposing exactly 5 tools to the client, the server sits in the ideal 3–15 tool coherence sweet spot.
• Ultra-Lean System Prompt Tax: Drops schema overhead from 27,681 tokens to 1,292 tokens (95.3% reduction), preserving context windows and maximizing LLM prompt-cache hits.
• Zero-Hop Hourly Drivers: The 3 operations developers and agents actually use constantly during pair-programming (get_file_contents, get_project, get_commit) remain eager tools for instant zero-hop execution.
• 100% Platform Access on Demand: The entire platform surface of 90 actions across 14 domains is accessible on-demand via dynamic action discovery (gitlab_find_actions $\rightarrow$ gitlab_execute_action), delivering 75%–96% token savings with default high-density Markdown tables and summaries (format: "markdown" | "json").
• Resilient Fallback: If an agent directly invokes any catalog action name (e.g. list_pipelines), the server dynamically executes it with full input validation and projection.

LLM Prompt Context (1,292 tokens total):

├── 1. gitlab_find_actions(query, [domain], [format]) [Meta Discovery] ├── 2. gitlab_execute_action(action, params, [format]) [Meta Dynamic Execution] ├── 3. get_file_contents(project_id, file_path, [ref]) [Eager Daily Driver #1] ├── 4. get_project(project_id, [statistics]) [Eager Daily Driver #2] └── 5. get_commit(project_id, sha) [Eager Daily Driver #3]

Under the hood (Dynamic Registry): └── 90 Curated Actions across 14 Domains (with 75%–99% token reduction projections)

Core Capabilities Across 14 Domains

1. Enterprise Observability & Self-Hosted Operations:

• System Health Diagnostics: End-to-end connectivity, token identity verification, and API latency testing (system_health_check).
• Push Mirrors: Verify upstream replication to remote Git hosts (list_push_mirrors) and force immediate sync (trigger_push_mirror_sync).
• CI Runners: Audit runner health, online/paused status, and tags (list_runners, get_runner_status).
• Webhooks: Inspect registered automation hooks (list_project_hooks).

1. Repository & Branch Governance: Project CRUD, group hierarchy resolution (buggycode/project-name), branch lifecycle, branch protection management (list_protected_branches, protect_branch, unprotect_branch), file/directory reading (get_file_contents), and atomic multi-file commits (push_files, create_commit).
2. CI/CD Observability: Query pipelines by status, trigger/cancel/retry pipelines (create_pipeline, cancel_pipeline, retry_pipeline), tail failed job logs (get_job_trace) without token blowout, read build artifacts (get_job_artifact_file), and inspect JUnit test reports (get_pipeline_test_report).
3. Merge Request Reviews & Diff Discussions: Two-stage diff inspection (get_merge_request_changes), automated lockfile pruning (package-lock.json), and inline diff discussions with SHA coordinate resolution (create_diff_discussion).
4. Issues & Task Planning: CRUD issues, track blockers/dependencies (list_issue_links, create_issue_link), and add progress notes (list_issue_notes, create_issue_note).
5. Milestones & Labels: Human-readable milestone resolution, label creation, and scoped milestone inspection.
6. Wikis & Snippets: Documentation outline slicing (toc_only: true), chapter extraction, and snippet management.
7. User & Identity Context: Authenticated identity lookup, group enumeration and creation (create_group), and owned project discovery.

Quickstart & Installation

Option 1: Run with npx (No installation needed)

npx -y @sumirati/mcp-gitlab

Option 2: Install Globally

npm install -g @sumirati/mcp-gitlab

mcp-gitlab

Option 3: Local Clone

git clone https://github.com/sumirati/mcp-gitlab.git

cd mcp-gitlab npm install npm test npm start

Environment Configuration

Client Configuration

Google Antigravity / Claude Desktop / Cursor

Add to your MCP configuration file (mcp_config.json or claude_desktop_config.json):

{

"mcpServers": { "gitlab": { "command": "npx", "args": ["-y", "@sumirati/mcp-gitlab"], "env": { "GITLAB_PERSONAL_ACCESS_TOKEN": " ", "GITLAB_API_URL": "https://gitlab.example.com/api/v4" } } } }

Complete Action Catalog Reference (90 Actions across 14 Domains)

All 90 actions feature strict input validation and field-mask projections:

1. The 5 Client-Exposed Tools (Hybrid Mode)

2. Enterprise & Self-Hosted Operations (enterprise — 6 actions)

3. Repository & Project Management (repositories — 10 actions)

| create_commit | Atomically commit multiple file additions, modifications, or updates to a target branch in a single Git commit using GitLab Commits API. Use for multi-file