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 · `gitl

... View full README on GitHub