gitlab-mcp

Lightweight MCP server for GitLab-centric code review workflows.

This project is intentionally narrow. It is designed for agents such as Codex, Cursor, and similar MCP-capable tools that need a compact integration focused on:

• merge request review by URL;
• reading merge request metadata, discussions, and pipelines;
• posting top-level review comments back to the merge request;
• researching the codebase in the context of an active review.

The server talks directly to the GitLab REST API. It does not require glab, and it resolves the target GitLab profile from the merge request URL.

Tooling Scope

Current tools:

• parse_merge_request_url
• get_merge_request
• get_merge_request_changes
• list_merge_request_discussions
• add_merge_request_note
• get_merge_request_pipelines

Why This Exists

General-purpose enterprise MCP servers are often too broad for review sessions. gitlab-mcp stays lightweight on purpose:

• focused on code review instead of full GitLab administration;
• compact payloads so an agent can reason over the response without wasting context;
• practical for repository investigation during review;
• limited write access: create a top-level merge request note when review output is ready.

If you want an agent to read a merge request, inspect discussions, examine changed files, and publish a review summary, this server is the intended integration point.

Requirements

• Python 3.13+
• uv
• a GitLab token with api scope
• network access to your GitLab instance

Version

• Current version: 0.1
• Release date: 2026-03-26

The CLI also exposes version output:

uv run gitlab-mcp --version
uv run gitlab-mcp -v

Configuration

The server reads profiles from:

~/.config/aka.NameRec@gmail.com/mcp/config.toml

You can override the location for testing with:

export AKA_MCP_CONFIG_PATH="/path/to/config.toml"

Example:

[gitlab]
profiles = [
  { base_url = "https://git.devcats.kg", token = "your-token" },
  { name = "gitlab-com", base_url = "https://gitlab.com", token = "other-token", auth_type = "bearer" }
]

Profile fields:

• base_url required and unique
• token required
• name optional; defaults to base_url
• auth_type optional: private_token or bearer
• verify_tls optional; defaults to true
• ca_bundle_path optional
• timeout_seconds optional

Local Run

uv run gitlab-mcp

The server uses stdio transport by default, which is the expected transport for a local MCP server in agent environments.

Install From GitHub URL

Repository URL:

git@github.com:aka-NameRec/gitlab-mcp.git

Minimal local install:

git clone git@github.com:aka-NameRec/gitlab-mcp.git
cd gitlab-mcp
uv sync

After that, register the server in your agent client using the repository directory as the working directory.

Codex example:

codex mcp add gitlab-review -- uv --directory /absolute/path/to/gitlab-mcp run gitlab-mcp

Cursor example:

{
  "mcpServers": {
    "gitlab-review": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/gitlab-mcp",
        "run",
        "gitlab-mcp"
      ]
    }
  }
}

Intended Agent UX

This repository is meant to be easy to install from a GitHub URL. A higher-level installer or agent can implement a flow like:

1. Clone the repository from GitHub.
2. Run uv sync in the cloned directory.
3. Register the MCP server with:

uv --directory /absolute/path/to/gitlab-mcp run gitlab-mcp

That makes requests such as install MCP server git@github.com:aka-NameRec/gitlab-mcp.git straightforward to automate in Codex, Cursor, or similar agents.

Notes

• The server resolves the target profile from the merge request URL host.
• Short merge request references such as !123 are intentionally unsupported.
• Configuration errors are raised as user-facing tool errors with actionable messages.
• add_merge_request_note posts a top-level comment, not an inline diff discussion.
• The diff tool trims oversized patches so the agent receives bounded review payloads.