gitlab-ci-mcp

gitlab-ci-mcp

适用于 GitLab CI/CD 的 MCP 服务。可让大模型 Agent（Claude Code、Cursor、OpenCode、DevX Agent 等）处理流水线、作业、计划、分支、标签、合并请求和仓库文件。

使用 Python、FastMCP 和 stdio 传输。

适用于任何 GitLab——SaaS gitlab.com 或可自托管／本地部署的实例。专为企业网络环境设计：支持配置 NO_PROXY 处理方式、可选的 SSL 验证开关，以及通过环境变量按项目限定范围。

设计亮点

• 工具注解——每个工具都带有 readOnlyHint / destructiveHint / idempotentHint / openWorldHint，以便 MCP 客户端对操作进行分类（例如，仅对 gitlab_merge_mr、gitlab_delete_schedule 等破坏性操作请求确认）。
• 每个工具都提供结构化输出——每个工具都声明了 TypedDict 返回类型，因此 FastMCP 会自动生成 outputSchema，且每个结果都会在预渲染的 Markdown 文本块旁提供 structuredContent。能够呈现结构化数据的客户端会使用该数据；偏好简洁文本的 Agent 则会使用 Markdown。无需 response_format 参数。
• 结构化错误——身份验证、404、403、429（速率限制）、5xx 和缺少环境变量等错误会转换为可操作的 ToolError 消息（例如 "GitLab authentication failed… verify GITLAB_TOKEN has api scope"），并作为 isError=True 结果返回。
• Pydantic 输入验证——每个参数都有带类型的约束（范围、长度、字面值），并会自动公开为 JSON Schema。
• 每次调用都可限定项目范围——每个工具都接受可选的 project_path，可覆盖 GITLAB_PROJECT_PATH，用于跨项目查询。
• 分页——列表工具会返回包含 page、total、has_more、next_page 的 pagination 块，并在 Markdown 页脚提供下一页提示。
• MCP Context 集成——gitlab_pipeline_health 和 gitlab_get_job_log 为 async，并通过 MCP Context 发送 info 日志／report_progress 事件，让客户端显示进度条。
• MCP 资源——gitlab://project/info 和 gitlab://project/ci-config 提供常见查询的对应资源，适用于偏好使用资源模型而非工具的客户端。
• 生命周期管理——服务器关闭时，通过 asynccontextmanager 生命周期钩子妥善关闭 python-gitlab HTTP 会话。
• 日志 grep——gitlab_get_job_log 接受 grep_pattern 和 grep_context（周边行），可通过正则表达式筛选数 MB 的 CI 日志，而无需将完整日志追踪加载到 Agent 上下文中。

线程模型

FastMCP 会自动在工作线程中运行同步工具 （anyio.to_thread.run_sync），因此它们不会阻塞 asyncio 事件循环—— python-gitlab 是一个同步库，如果我们将每次调用都自行封装在 asyncio.to_thread 中，只会徒增繁琐代码。需要使用 MCP Context（进度、info 日志）的工具会编写为 async def，并显式 使用 asyncio.to_thread 封装 python-gitlab 调用。

功能

涵盖日常 CI/CD 工作所需的 23 个工具：

流水线 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

计划任务 gitlab_list_schedules · gitlab_create_schedule · gitlab_update_schedule · gitlab_delete_schedule

分支和标签 gitlab_list_branches · gitlab_list_tags · gitlab_compare_branches

合并请求 gitlab_list_merge_requests · gitlab_get_merge_request · gitlab_get_merge_request_changes · gitlab_create_merge_request · gitlab_merge_mr

仓库和项目 gitlab_get_file · gitlab_list_repository_tree · gitlab_project_info

流水线健康报告

gitlab_pipeline_health 会返回一份可直接阅读的摘要，涵盖过去 7/30 天：

Last 7d:  96.4%  up   | 27/28 success
Last 30d: 92.1%       | 105/114 success
Last 10:  success success success failed success ...

适用于值班 / 问题排查：покажи health master за последние 7 дней。

安装

需要 Python 3.10+。

# via uvx (recommended)
uvx --from gitlab-ci-mcp gitlab-ci-mcp

# or via pip/pipx
pipx install gitlab-ci-mcp

配置

所有配置均通过环境变量设置：

变量	必填	说明
GITLAB_URL	是	基础 URL，例如 https://gitlab.example.com
GITLAB_TOKEN	是	具有 api 范围的个人访问令牌
GITLAB_PROJECT_PATH	是	默认项目，例如 my-org/my-repo
GITLAB_SSL_VERIFY	否	true（默认值）/ false
GITLAB_NO_PROXY_DOMAINS	否	以逗号分隔的域名，将添加到 NO_PROXY 中（适用于通过本地 HTTP 代理访问网络的公司网络环境，例如 .corp.example.com,gitlab.internal）

每个工具都接受可选的 project_path 参数，可在每次调用时覆盖 GITLAB_PROJECT_PATH，适用于跨项目查询。

Claude Code

完整指南： docs/claude-code.md — 前置条件、两种安装方式、多项目配置、通过公司代理访问自托管 GitLab、故障排除、卸载。

简要步骤：

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

或者在 ~/.claude.json / 项目 .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"
      }
    }
  }
}

检查：

claude mcp list
# gitlab: uvx --from gitlab-ci-mcp gitlab-ci-mcp - ✓ Connected

Cursor / OpenCode / DevX Agent

方法相同——将 MCP 配置指向 uvx --from gitlab-ci-mcp gitlab-ci-mcp，并使用上述环境变量。请参阅各工具自己的 MCP 配置语法。

示例提示词

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

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

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

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

速率限制和连接复用

GitLab 对每位用户实施速率限制（REST API 通常为 2000 次请求/小时，可由管理员配置——请查看实例的 /admin/application_settings/network）。

• 服务会按 project_path 缓存一个 python-gitlab HTTP 会话，因此对同一项目的重复工具调用会复用连接，无需每次重新进行身份验证。
• 列表工具默认使用 per_page=20，确保单次调用只需发出少量 API 请求。
• 如果遇到 429 Too Many Requests，错误处理程序会返回可执行的提示——请稍后重试，并增大 per_page 或减少调用次数。

通过公司代理访问自托管 GitLab

如果笔记本电脑使用本地 HTTP 代理（例如用于公司网络访问的 http://127.0.0.1:3128），而 GitLab 位于内网，代理会拦截并中断内网请求。有两种解决方案：

1. 设置 GITLAB_NO_PROXY_DOMAINS——服务将在启动时将这些域名添加到 NO_PROXY，并从自身进程中清除 HTTP_PROXY/HTTPS_PROXY，以免影响 GitLab 流量。
2. 在 MCP 的 env 部分显式传入空值 HTTP_PROXY="" 等。

开发

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

直接运行服务（stdio 传输，等待从 stdin 接收 MCP 消息）：

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

许可证

MIT — 请参阅 LICENSE。

致谢

基于 python-gitlab 和 MCP Python SDK 构建。