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 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).
2. 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).
3. 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).
4. 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).
5. Issues & Task Planning: CRUD issues, track blockers/dependencies (list_issue_links, create_issue_link), and add progress notes (list_issue_notes, create_issue_note).
6. Milestones & Labels: Human-readable milestone resolution, label creation, and scoped milestone inspection.
7. Wikis & Snippets: Documentation outline slicing (toc_only: true), chapter extraction, and snippet management.
8. 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": "<your-gitlab-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)

4. Branch Governance (branches — 7 actions)

5. Git Commits & History (commits — 2 actions)

6. Pipelines & CI/CD Observability (pipelines — 10 actions)

7. Merge Requests & Code Reviews (merge-requests — 12 actions)

8. Issues & Roadmaps (issues — 8 actions)

9. Milestones & Labels (milestones — 6 actions)

10. Releases & Tags (releases — 5 actions)

11. Project Collaborators & Roles (members — 5 actions)

12. CI/CD Environment Variables (variables — 5 actions)

13. Wikis & Documentation (wikis — 4 actions)

14. Snippets & Code Pastes (snippets — 4 actions)

15. User & Group Context (user — 6 actions)

Benchmarks: Token Economy in Action

Reproducible deterministic benchmark (node test/benchmark-test.js & node test/catalog-execution-test.js) measured against canonical GitLab REST API v4 payloads (test/fixtures/gitlab-api-v4-fixtures.js, token count = Math.ceil(utf8Bytes / 4)):

Complete 90-Action Catalog Benchmark (Across All 14 Domains)

Measured across all 90 handlers via node test/catalog-execution-test.js:

Key Token Optimization Pillars:

• Smart Diff & Lockfile Truncation: Commit diffs (get_commit) and MR changes (get_merge_request_changes) automatically collapse dependency lockfiles (package-lock.json, pnpm-lock.yaml, yarn.lock, go.sum, Cargo.lock, *.min.js) via ignore_lockfiles: true by default, saving 1,000–3,000 tokens per review. Pass ignore_lockfiles: false if full lockfile diffs are required.
• Conservative Default Pagination: All list actions default to per_page: 10 (max: 100), eliminating token waste from loading 20–50 items when only recent entries are needed.
• Default High-Density Markdown Format: Discovery (gitlab_find_actions), execution (gitlab_execute_action), project info (get_project), file inspection (get_file_contents), and commit inspection (get_commit) default to format: "markdown", yielding 75%–96% token reductions for structured metadata.
• Recursive Output Projection Filter (projectOutput): Strips GitLab REST API v4 noise metadata keys (_links, avatar_url, references, time_stats, task_completion_status, commands_changes, user_notes_count, merge_requests_count, upvotes, downvotes, subscribed, has_tasks, service_desk_reply_to, moved_to_id, container_expiration_policy, permissions, and null/empty fields) before payloads reach LLM context.

Roadmap

Upcoming (v3.2)

• [x] Upstream indexed filtering & strict pagination caps (state, labels, milestone, author_id, assignee_id)
• [x] Client error resilience (401 probe disambiguation, 403 insufficient scope, 429 rate limit backoff, 201 ghost write guard)
• [x] Hardened output projection with recursion depth guard (maxDepth = 32) and empty collection preservation
• [x] Nested subgroup hierarchy management (create_group with parent_id)
• [x] Smart CI/CD failure log extraction & ANSI sequence stripping in get_job_trace (strip_ansi, smart_failure)
• [x] Outline-first code symbol extraction & line range slicing in get_file_contents (outline_only, start_line, end_line)
• [ ] Pre-flight mergeability & conflict verification (get_mergeability)
• [ ] Token scope self-auditing & permission pre-flight

Future Horizons (v3.x)

• [ ] Standardized collection _summary headers to facilitate multi-turn history pruning in LiteLLM / Eigent agent orchestration
• [ ] Remote Transports: Streamable SSE and HTTP remote server modes
• [ ] Scoped GraphQL query engine for relational deep inspections
• [ ] DevSecOps vulnerability & secret scanning alert queries
• [ ] Scoped & rate-guarded code search within project repositories

Acknowledgements & Lineage

This project incorporates architectural concepts, schemas, and patterns from:

• @modelcontextprotocol/server-gitlab (MIT License) — Copyright (c) 2024 Anthropic, PBC / GitLab, PBC. Baseline repository and file schema patterns.
• @modelcontextprotocol/sdk (MIT License) — Copyright (c) Anthropic, PBC.
• zod (MIT License) — Colin McDonnell.
• GitLab REST API v4 — GitLab, PBC.
• jmrplens/gitlab-mcp-server — Dynamic action discovery and meta-dispatcher pattern concepts.
• Architectural patterns evaluated from Vijay-Duke/mcp-gitlab and zereight/gitlab-mcp.

See NOTICE for complete third-party attribution details.

License

This project is licensed under the MIT License — Copyright (c) 2026 sumirati@buggycode.net.