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, FastMCP, stdio transport.

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.

• Project scoping per call — every tool accepts an optional project_path that overrides GITLAB_PROJECT_PATH for cross-project queries.

• Pagination — list tools return a pagination block with page, total, has_more, next_page and a next-page hint in the markdown footer.

• MCP Context integration — gitlab_pipeline_health and gitlab_get_job_log are async and emit info logs / report_progress events through the MCP Context so clients can show progress bars.

• 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

23 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

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 an optional project_path arg that overrides GITLAB_PROJECT_PATH per call — useful for cross-project queries.

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 gitlab uvx --from gitlab-ci-mcp gitlab-ci-mcp \
  --env GITLAB_URL=https://gitlab.example.com \
  --env GITLAB_TOKEN=glpat-xxxxxx \
  --env GITLAB_PROJECT_PATH=my-org/my-repo

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_TOKEN}",
        "GITLAB_PROJECT_PATH": "my-org/my-repo",
        "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 one python-gitlab HTTP session per project_path, so repeated tool calls against the same project reuse the connection and do not re-authenticate each time.

• 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, waits on stdin for MCP messages):

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

License

MIT — see LICENSE.

Acknowledgements

Built on python-gitlab and the MCP Python SDK.