gitlab-ci-mcp

用于 GitLab CI/CD 的 MCP 服务器。允许 LLM 代理（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。能够渲染结构化数据的客户端会使用它；偏好紧凑文本的代理则获取 markdown。无需 response_format 参数。

• 结构化错误 — 身份验证、404、403、429（速率限制）、5xx、缺少环境变量等错误会被转换为可操作的 ToolError 消息（例如：“GitLab 身份验证失败……请验证 GITLAB_TOKEN 是否具有 api 作用域”）并作为 isError=True 的结果呈现。

• Pydantic 输入验证 — 每个参数都有类型约束（范围、长度、字面量），并自动作为 JSON Schema 公开。

• 按调用进行项目作用域划分 — 每个工具都接受一个可选的 project_path，它会覆盖 GITLAB_PROJECT_PATH 以进行跨项目查询。

• 分页 — 列表工具返回一个包含 page、total、has_more、next_page 的 pagination 块，并在 markdown 页脚中提供下一页提示。

• MCP 上下文集成 — gitlab_pipeline_health 和 gitlab_get_job_log 是 async 的，并通过 MCP 上下文发出 info 日志 / report_progress 事件，以便客户端可以显示进度条。

• MCP 资源 — gitlab://project/info 和 gitlab://project/ci-config 为偏好资源模型而非工具的客户端提供了常见的查找功能。

• 生命周期管理 — python-gitlab HTTP 会话通过 asynccontextmanager 生命周期钩子在服务器关闭时被妥善关闭。

• 日志 grep — gitlab_get_job_log 接受 grep_pattern + grep_context（周围行），用于对兆字节级的 CI 日志进行正则过滤，而无需将整个跟踪拉入代理上下文。

线程模型

FastMCP 会自动在工作线程中运行同步工具（anyio.to_thread.run_sync），因此它们不会阻塞 asyncio 事件循环 — python-gitlab 是一个同步库，如果我们自己将每个调用包装在 asyncio.to_thread 中会显得过于繁琐。受益于 MCP 上下文（进度、信息日志）的工具被编写为 async def，并显式地用 asyncio.to_thread 包装 python-gitlab 调用。

功能

23 个工具涵盖了日常 CI/CD 的方方面面：

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

配置

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

每个工具都接受一个可选的 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 代理（例如用于企业 Web 访问的 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 构建。