GitLab MCP Server (@sumirati/mcp-gitlab)

A robust, developer-ready, and LLM-ergonomic Model Context Protocol (MCP) server for both self-hosted GitLab Community Edition (CE) and GitLab Enterprise Edition (EE).

Mission

MCP-gitlab provides high-signal, LLM-optimized access to GitLab instances. Rather than dumping raw API payloads, it focuses on context efficiency, developer ergonomics, and native AI pair-programming workflows for codebase management, task coordination, CI/CD observability, and release delivery.

Core Pillars & Capabilities

1. Task & Project Planning

• Full Issue Lifecycle: CRUD operations, filtering by state, milestone, label, author, and assignee with clean summaries.
• Smart Milestone Management: Full CRUD with automatic resolution of human-readable milestone_title to internal numeric IDs.
• Task Dependencies (issue_links): First-class tracking of blocks, is_blocked_by, and relates_to relationships for AI roadmap planning and dependency graphs.
• Discussions & Progress Tracking (issue_notes): Post progress logs, test results, or design rationale directly to issues without modifying descriptions.

2. CI/CD & Test Observability

• Pipelines & Job Inspection: Query pipelines by branch, commit SHA, or execution status (running, failed, success).
• Safe Job Log Tailing (get_job_trace): Safely tail test/build logs (tail_lines) so agents can inspect stack traces directly without token overflow.
• JUnit Test Reports (get_pipeline_test_report): High-level test suite breakdowns (total, passed, failed, failure messages).

3. Release & Version Delivery

• GitLab Releases API: Create and inspect formal GitLab releases linked to Git tags, milestones, and markdown changelogs.
• Git Tags: List and create semantic version tags (vX.Y.Z).

4. Merge Request Review & Delivery

• Full MR Lifecycle: Create, inspect, update, and accept/merge MRs with branch cleanup and squash options.
• Diff Reviews (get_merge_request_changes): Review code diffs and post review comments (create_merge_request_note).

LLM-First Architectural Principles

• Context Token Economy: Lean response payloads by default returning high-signal summaries instead of thousands of lines of raw GitLab API metadata.
• Smart Auto-Resolution: Transparently resolves paths (e.g. 'group/project-name' vs numeric 31), milestone titles, and label strings/arrays.
• Self-Hosted & CE First: Zero dependencies on GitLab Duo or enterprise licenses; connects over standard v4 REST using a Personal Access Token (PAT).

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
# Or from GitLab.com:
# git clone https://gitlab.com/sumirati/mcp-gitlab.git

cd mcp-gitlab
npm install
node index.js

Environment Configuration

Configure the following environment variables (or copy .env.example to .env):

Client Configuration

Google Antigravity / Claude Desktop / Cursor

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

Using npm / npx:

{
  "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"
      }
    }
  }
}

Using local repository:

{
  "mcpServers": {
    "gitlab": {
      "command": "node",
      "args": ["/path/to/MCP-gitlab/index.js"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "<your-gitlab-token>",
        "GITLAB_API_URL": "https://gitlab.example.com/api/v4"
      }
    }
  }
}

Complete Tools Reference

The server exposes 39 tools organized across key functional domains:

Repository & Files

Issues & Notes

Milestones & Labels

CI/CD Pipelines & Test Observability

Releases & Tags

Merge Requests

Roadmap

• Read-Only Mode (GITLAB_READ_ONLY=true): Safeguard enabling AI agents to read, query, and diagnose GitLab assets without permission to perform write operations, commits, or state changes.
• Inline Diff Reviews: Add support for posting review comments directly to specific diff lines/positions on Merge Requests (create_diff_discussion).
• Project Wiki & Snippets Support: Expand tooling to read and update GitLab project wikis and code snippets.
• Streamable HTTP Remote Transport: Support running as a remote/hosted MCP service alongside the default local stdio transport.

Acknowledgements & Third-Party 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 & zod-to-json-schema (MIT License) — Colin McDonnell & Stefan Evertsson.
• GitLab REST API v4 — GitLab, PBC.
• 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.