SuperAPI AI Directory
Partner with us中文AI newsFavorites
All toolsAI developer platformsgitlab-ci-mcp

gitlab-ci-mcp

GitLab CI/CD pipelines, jobs, schedules, merge requests and files, for GitLab SaaS or self-hosted instances.

Open website

About this tool

Purpose

gitlab-ci-mcp is an MCP (Model Context Protocol) server for GitLab CI/CD. Its goal is to enable LLM agents (officially listed examples include Claude Code, Cursor, OpenCode, DevX Agent, etc.) to interact directly with GitLab's pipelines, jobs, schedules, branches, tags, merge requests, and repository files. It supports any GitLab, including both gitlab.com SaaS and self-hosted/on-premises instances. The project is designed with enterprise networks in mind, providing configurable NO_PROXY handling, an optional SSL verification toggle, and per-project scoping via environment variables.

Main Capabilities

The project provides 23 tools covering the daily CI/CD operation 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 and 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 and project: gitlab_get_file, gitlab_list_repository_tree, gitlab_project_info.

Among these, gitlab_pipeline_health returns a ready-to-read summary covering 7/30 days, suitable for on-call and triage scenarios.

It also includes the following design features:

  • Tool annotations: each tool carries readOnlyHint / destructiveHint / idempotentHint / openWorldHint, making it easy for MCP clients to classify operations (for example, requesting confirmation only for destructive operations such as gitlab_merge_mr and gitlab_delete_schedule).
  • Structured output: each tool declares a TypedDict return type, FastMCP automatically generates an outputSchema, and each result carries structuredContent in addition to a pre-rendered markdown text block. Clients that support structured data use the structured data, while agents that prefer compact text use the markdown, with no response_format parameter needed.
  • Structured errors: errors such as authentication, 404, 403, 429 (rate limiting), 5xx, and missing environment variables are converted into actionable ToolError messages (for example, "GitLab authentication failed… verify GITLAB_TOKEN has api scope") and returned as results with isError=True.
  • Pydantic input validation: every parameter has typed constraints (range, length, literal), automatically exposed as JSON Schema.
  • Per-call project scoping: every tool accepts an optional project_path parameter that overrides GITLAB_PROJECT_PATH, making cross-project queries easy.
  • Pagination: list tools return pagination blocks containing page, total, has_more, next_page, and provide a next-page hint in the markdown footer.
  • MCP Context integration: gitlab_pipeline_health and gitlab_get_job_log are asynchronous and emit info logs / report_progress events through the MCP Context, allowing clients to display progress bars.
  • MCP Resources: gitlab://pproject/info and gitlab://project/ci-config are common queries for clients that prefer the Resource model.
  • Lifecycle management: through the asynccontextmanager lifecycle hook, cleanly close the python-gitlab HTTP session when the server shuts down.
  • Log grep: gitlab_get_job_log accepts grep_pattern and grep_context (number of lines before and after), which can use regular expressions to filter megabyte-scale CI logs, avoiding pulling the entire trace into the agent context.

Usage

Requires Python 3.10+. All configuration is done through environment variables. Installation and running methods include: pointing to uvx --from gitlab-ci-mcp gitlab-ci-mcp in the MCP configuration and carrying the corresponding environment variables; it can also be configured in ~/.claude.json or the project .mcp.json. The MCP server's directory structure, installation paths, and specific configuration snippets are detailed in the full documentation docs/claude-code.md—including prerequisites, two installation paths, multi-project setup, self-hosted GitLab behind an enterprise proxy, troubleshooting, and uninstallation.

Simply run the server directly with stdio transport (waiting for MCP messages on stdin):

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

Each tool accepts an optional project_path parameter, used to override GITLAB_PROJECT_PATH per call.

Threading Model

FastMCP automatically runs synchronous tools in a worker thread (anyio.to_thread.run_sync), so it does not block the asyncio event loop—python-gitlab is a synchronous library, and wrapping every call in asyncio.to_thread yourself would be unnecessary ceremony. Tools that need an MCP Context (progress, info logging) are written as async def and explicitly wrap python-gitlab calls with asyncio.to_thread.

Suitable Scenarios

  • Involving LLM agents in CI/CD troubleshooting and triage, for example querying the pipeline health of a branch over the last 7 days.
  • Triggering, retrying, and canceling pipelines through an agent, managing schedules, branches, tags, and merge requests.
  • Cross-project queries: using the optional project_path parameter to perform operations on different projects.
  • Enterprise intranet environments: when self-hosted GitLab is behind a corporate proxy, proxy issues can be handled through GITLAB_NO_PROXY_DOMAINS or by explicitly setting an empty HTTP_PROXY.
  • Filtering by regular expression in large CI logs: use grep_pattern and grep_context to avoid pulling the full trace.

Limitations and Notes

  • GitLab has rate limits per user (the REST API is usually 2000 requests/hour, configurable by administrators, see the instance's /admin/application_settings/network).
  • The server caches one python-gitlab HTTP session per project_path; repeated calls to 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 encounter 429 Too Many Requests, the error handler returns an actionable message, suggesting waiting and retrying with a larger per_page or fewer calls.
  • When the laptop uses a local HTTP proxy (for example, corporate network accessused by http://127.0.0.1:3128）而 GitLab on the intranet, the proxy will intercept and interrupt intranet requests; you can set GITLAB_NO_PROXY_DOMAINS to have the server add these domains to NO_PROXY at startup and clear HTTP_PROXY / HTTPS_PROXY from its own process, or explicitly pass an empty HTTP_PROXY="" in the MCP env section.

License and Dependencies

The project uses the MIT license, see LICENSE for details. Built on top of python-gitlab and the MCP Python SDK. Other information not provided in the materials (such as specific pricing, charging models, etc.) is not yet available.

Related tools

Browse category