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/openWorldHintso MCP clients can classify operations (e.g. ask for confirmation only on destructive ones likegitlab_merge_mr,gitlab_delete_schedule). - Structured output on every tool — each tool declares a TypedDict return type, so FastMCP auto-generates an
outputSchemaand every result carriesstructuredContentalongside a pre-rendered markdown text block. Clients that can render structured data use it; agents that prefer compact text get the markdown. Noresponse_formatparameter needed. - Structured errors — authentication, 404, 403, 429 (rate-limit), 5xx, missing-env errors are converted to actionable
ToolErrormessages (e.g. "GitLab authentication failed… verify GITLAB_TOKEN hasapiscope") and surfaced asisError=Trueresults. - 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_paththat overridesGITLAB_PROJECT_PATHfor cross-project queries. - Pagination — list tools return a
paginationblock withpage,total,has_more,next_pageand a next-page hint in the markdown footer. - MCP Context integration —
gitlab_pipeline_healthandgitlab_get_job_logareasyncand emitinfologs /report_progressevents through the MCP Context so clients can show progress bars. - MCP Resources —
gitlab://project/infoandgitlab://project/ci-configmirror common lookups for clients that prefer the Resource model over tools. - Lifespan management —
python-gitlabHTTP sessions are closed cleanly on server shutdown via anasynccontextmanagerlifespan hook. - Log grep —
gitlab_get_job_logacceptsgrep_pattern+grep_context(surrounding lines) for regex-filtering megabyte-scale CI logs without pulling the whole trace into agent context.






