GitLab MCP

FastMCP plugin for GitLab repository workflows. The compatibility target is GitLab 16.11.10 with the GitLab API v4, using uv, fastmcp, and python-gitlab.

The current catalog exposes 141 repository-centered MCP tools. Destructive tools, such as deletes, cancel, stop, unprotect, and merge acceptance, require an exact confirm string before they call GitLab.

Personas

• Tech Lead: repository health, branches, merge requests, code review, approval posture, discussions, and protections.
• PO: issues, issue discussions, labels, milestones, release state, delivery status, and release links.
• Dev: repository tree, files, commits, branches, merge requests, diff versions, review discussions, and pipeline feedback.
• DevOps: pipelines, jobs, artifacts, variables, environments, releases, protected refs, and external checks.

Configuration

Set these environment variables before starting the MCP server:

export GITLAB_URL="https://gitlab.example.com"
export GITLAB_TOKEN="glpat-..."

Optional variables:

• GITLAB_OAUTH_TOKEN
• GITLAB_JOB_TOKEN
• GITLAB_SSL_VERIFY (true or false, default true)
• GITLAB_MCP_USE_SYSTEM_TRUSTSTORE (true or false, default true)
• GITLAB_TIMEOUT (seconds, default 30)
• GITLAB_API_VERSION (default 4)
• GITLAB_MCP_LOG_LEVEL (DEBUG, INFO, WARNING, ERROR, default INFO)
• GITLAB_MCP_LOG_JSON (true or false, default false)
• GITLAB_MCP_LOG_BACKTRACE (true or false, default false)
• GITLAB_MCP_LOG_DIAGNOSE (true or false, default false)
• GITLAB_MCP_LOG_ENQUEUE (true or false, default false)
• GITLAB_MCP_LOG_FORMAT (Loguru format string)

Logs are written to stderr so they do not interfere with MCP stdio transport. When TLS verification is enabled, truststore is used by default so Python can validate GitLab certificates against the local operating system trust store.

Run

uv sync --dev
uv run gitlab-mcp

The plugin manifest points Codex to .mcp.json, which runs the same command through uv.

Tests

uv run pytest tests/unit -q

The GitLab 16.11.10 E2E test is opt-in because the container is large and slow:

GITLAB_MCP_RUN_E2E=1 uv run pytest tests/e2e -m real_gitlab -q

The E2E suite starts one GitLab 16.11.10 container and runs workflow tests for repository operations, issue planning, merge request review and diff versions, commit collaboration, protected tags, release links, and DevOps/release metadata.

See docs/tool-catalog.md for the full tool list and docs/collaboration-tool-matrix.md for the role matrix behind notes and discussion tools. See docs/architecture.md for the hexagonal architecture boundaries and tool registration flow. See docs/mcp-exposition.md for the MCP safety annotations, metadata, and error handling conventions. See docs/python-gitlab-audit.md for the executable audit matrix against python-gitlab manager metadata. See docs/python-gitlab-tool-matrix.md for the per-tool mapping to python-gitlab functions and managers.