GitLab Ci MCP

gitlab-ci-mcp

MCP server for GitLab CI/CD. Lets an LLM agent (Claude Code, Cursor, OpenCode, DevX Agent, etc.) work with pipelines, jobs, schedules, branches, tags, merge requests and repository files.

Python and FastMCP. Local stdio remains the default; opt-in Streamable HTTP supports shared deployments with one GitLab PAT per caller.

Works with any GitLab — SaaS gitlab.com or self-hosted / on-prem. Designed with corporate networks in mind: configurable NO_PROXY handling, optional SSL-verify toggle, per-project scoping via env vars.

Design highlights

• Tool annotations — every tool carries readOnlyHint / destructiveHint / idempotentHint / openWorldHint so MCP clients can classify operations (e.g. ask for confirmation only on destructive ones like gitlab_merge_mr, gitlab_delete_schedule).
• Structured output on every tool — each tool declares a TypedDict return type, so FastMCP auto-generates an outputSchema and every result carries structuredContent alongside a pre-rendered markdown text block. Clients that can render structured data use it; agents that prefer compact text get the markdown. No response_format parameter needed.
• Structured errors — authentication, 404, 403, 429 (rate-limit), 5xx, missing-env errors are converted to actionable ToolError messages (e.g. _"GitLab authentication failed… verify GITLAB_TOKEN has api scope"_) and surfaced as isError=True results.
• Pydantic input validation — every argument has typed constraints (ranges, lengths, literals) auto-exposed as JSON Schema.
• Explicit project scoping — every GitLab tool requires project_path by default. Set GITLAB_ALLOW_DEFAULT_PROJECT=true to opt into the legacy environment fallback.
• Pagination — list tools return a pagination block with page, total, has_more, next_page and a next-page hint in the markdown footer.
• Per-user HTTP credentials — in Streamable HTTP mode every request must carry X-GitLab-Token; GitLab API calls and cached clients are isolated by PAT. Stdio remains single-user with GITLAB_TOKEN.
• MCP Resources — gitlab://project/info and gitlab://project/ci-config mirror common lookups for clients that prefer the Resource model over tools.
• Lifespan management — python-gitlab HTTP sessions are closed cleanly on server shutdown via an asynccontextmanager lifespan hook.
• Log grep — gitlab_get_job_log accepts grep_pattern + grep_context (surrounding lines) for regex-filtering megabyte-scale CI logs without pulling the whole trace into agent context.

Threading model

FastMCP automatically runs synchronous tools in a worker thread (anyio.to_thread.run_sync), so they do not block the asyncio event loop — python-gitlab is a synchronous library and wrapping every call in asyncio.to_thread ourselves would be ceremony. Tools that benefit from the MCP Context (progress, info logs) are written as async def and explicitly wrap python-gitlab calls with asyncio.to_thread.

Features

24 tools covering the everyday CI/CD surface:

Pipelines gitlab_list_pipelines · gitlab_get_pipeline · gitlab_get_pipeline_jobs · gitlab_get_job_log · gitlab_trigger_pipeline · gitlab_retry_pipeline · gitlab_cancel_pipeline · gitlab_pipeline_health

Schedules gitlab_list_schedules · gitlab_create_schedule · gitlab_update_schedule · gitlab_delete_schedule

Branches & tags gitlab_list_branches · gitlab_list_tags · gitlab_compare_branches

Merge requests gitlab_list_merge_requests · gitlab_get_merge_request · gitlab_get_merge_request_changes · gitlab_create_merge_request · gitlab_merge_mr

Repository & project gitlab_get_file · gitlab_list_repository_tree · gitlab_project_info

Package gitlab_ci_mcp_check_updates

Pipeline health report

gitlab_pipeline_health returns a ready-to-read summary over 7/30 days:

Last 7d:  96.4%  up   | 27/28 success

Last 30d: 92.1% | 105/114 success Last 10: success success success failed success ...

Handy for on-call / triage: покажи health master за последние 7 дней.

Installation

Requires Python 3.10+.

# via uvx (recommended)

uvx --from gitlab-ci-mcp gitlab-ci-mcp

or via pip/pipx

pipx install gitlab-ci-mcp

Configuration

All config is via environment variables:

Every tool accepts a project_path arg. It is required by default so a call cannot silently target an environment-wide project. For legacy deployments, set GITLAB_ALLOW_DEFAULT_PROJECT=true together with GITLAB_PROJECT_PATH to opt into the old fallback behavior.

Update checking is disabled by default. Set MCP_GITLAB_UPDATE_CHECK_ENABLED=true to enable the explicit gitlab_ci_mcp_check_updates tool. When enabled, it makes one bounded request to fixed PyPI JSON, caches a result for five minutes, reports failures and unsupported versions, and never installs anything. No startup or other tool call performs this request. If called while disabled, the tool reports disabled without making a network request.

Pipeline health success rate uses completed pipelines only: success and failed are in the denominator; running, pending, manual, canceled, skipped, and other non-completed statuses are excluded. A missing comparison period or a sample without completed pipelines is reported as insufficient data, not as a zero rate or a flat trend.

Shared Streamable HTTP deployment

For a shared server, run with MCP_TRANSPORT=streamable-http. Each caller must send their own GitLab PAT in X-GitLab-Token; the server never falls back to the process GITLAB_TOKEN in this mode. GitLab applies that PAT's identity and permissions to each API operation. The header is a custom credential mechanism, not MCP OAuth; clients need support for configured custom headers.

The server binds to loopback (127.0.0.1:8000) by default. Expose it through an HTTPS reverse proxy, restrict network access, and redact the PAT header from proxy, tracing, and error logs. Initialize and tool discovery only check that the header is non-empty; GitLab validates the PAT when an API call is made.

Example for Claude Code (provide GITLAB_PAT through a secret manager; do not put a literal token in shell history):

claude mcp add --transport http \

--header "X-GitLab-Token: ${GITLAB_PAT}" \ gitlab https://mcp.example.com/mcp

The client must attach the header to every request. Each GitLab tool still requires an explicit project_path. Fixed resources gitlab://project/info and gitlab://project/ci-config have no project argument; they require the explicit compatibility setting GITLAB_ALLOW_DEFAULT_PROJECT=true and GITLAB_PROJECT_PATH.

Full credential details and limitations: docs/per-user-auth.md.

Claude Code

Full walkthrough: docs/claude-code.md — prerequisites, two install paths, multi-project setup, self-hosted GitLab behind a corp proxy, troubleshooting, uninstall.

Short version:

claude mcp add --transport stdio \

--env GITLAB_URL=https://gitlab.example.com \ --env GITLAB_TOKEN="$GITLAB_PAT" \ gitlab -- uvx --from gitlab-ci-mcp gitlab-ci-mcp

Each GitLab tool call must include project_path, for example project_path="my-org/my-repo". For legacy default-project behavior, also set GITLAB_PROJECT_PATH and GITLAB_ALLOW_DEFAULT_PROJECT=true.

Or in ~/.claude.json / project .mcp.json:

{

"mcpServers": { "gitlab": { "type": "stdio", "command": "uvx", "args": ["--from", "gitlab-ci-mcp", "gitlab-ci-mcp"], "env": { "GITLAB_URL": "https://gitlab.example.com", "GITLAB_TOKEN": "${GITLAB_PAT}", "GITLAB_PROJECT_PATH": "my-org/my-repo", "GITLAB_ALLOW_DEFAULT_PROJECT": "true", "GITLAB_SSL_VERIFY": "true" } } } }

Check:

claude mcp list

gitlab: uvx --from gitlab-ci-mcp gitlab-ci-mcp - ✓ Connected

Cursor / OpenCode / DevX Agent

Same idea — point the MCP config to uvx --from gitlab-ci-mcp gitlab-ci-mcp with the env vars above. See each tool's own MCP config syntax.

Example prompts

что сломалось в последнем pipeline master

покажи health master за 7 дней для проекта my-org/other-repo

создай MR из feature/foo в master с title "feat: foo"

покажи содержимое .gitlab-ci.yml из master

Rate limits & connection reuse

GitLab enforces a per-user rate limit (typically 2000 req/h for the REST API, configurable by the admin — see your instance's /admin/application_settings/network).

• The server caches a bounded python-gitlab HTTP session per GitLab URL, project, and PAT fingerprint. Different users never reuse one another's cached client.
• List tools default to per_page=20 to keep a single call within a small number of API requests.
• If you hit a 429 Too Many Requests, the error handler returns an actionable message — wait and try again with larger per_page or fewer calls.

Self-hosted GitLab behind a corporate proxy

When your laptop has a local HTTP proxy (e.g. http://127.0.0.1:3128 for corp web access) but GitLab is on the intranet, the proxy intercepts and kills internal requests. Two options:

1. Set GITLAB_NO_PROXY_DOMAINS — the server will add them to NO_PROXY at startup and clear `HTTP_PROXY`/`HTTPS_PROXY` from its own process so they don't affect GitLab traffic.
2. Pass explicitly empty HTTP_PROXY="" etc. in the MCP env section.

Development

git clone https://github.com/mshegolev/gitlab-ci-mcp

cd gitlab-ci-mcp python -m venv .venv && . .venv/bin/activate pip install -e '.[dev]' pytest

Run the server directly (stdio transport is the default and waits on stdin for MCP messages):

GITLAB_URL=... GITLAB_TOKEN=... gitlab-ci-mcp

License

MIT — see LICENSE.

Acknowledgements

Built on python-gitlab and the MCP Python SDK.