zereight/gitlab-mcp

什么是 GitLab MCP 服务器？

gitlab-mcp 是一个独立的模型上下文协议（MCP）服务器，允许 AI 代理（Claude、Codex、Cursor、VS Code、Copilot 等）与 GitLab 实例通信。它将 GitLab REST/GraphQL API 封装在 MCP 接口后面，暴露数百个即用型工具（例如 create-merge-request、list-issues、run-pipeline、read-wiki），LLM 可以直接调用。

为什么存在

官方的 GitLab MCP 服务器内置于 GitLab 中，相对较重。gitlab-mcp 是一个轻量级、一次性安装的二进制文件，可以在本地、容器或自定义自托管 GitLab 上运行。
它针对 AI 代理工作流进行了优化 – 工具被分组为 工具集，支持两步 MR 差异审查、JMESPath 结果过滤和细粒度权限模式。
它通过 stdio、服务器发送事件（SSE）或可流式 HTTP 与许多 MCP 客户端（Claude Code、Codex、Cursor、VS Code、Copilot、基于 JSON 的客户端）配合使用。

主要功能（如 README 中所述）

功能	含义
275 个工具（工具集中 273 个 + `execute_graphql` + `discover_tools`）	一个大型工具箱；您可以从最小的核心集开始，并在运行时启用更多。
2 步 MR 审查	首先列出更改的文件，然后批量获取差异 – 这种模式与代理推理代码更改的方式相匹配。
内置代理技能	预写的“技能”（提示式指导）位于 `skills/gitlab-mcp/` 下，帮助代理正确使用工具。
灵活的认证	个人访问令牌（PAT）、本地 OAuth2 浏览器流程、MCP 代理 OAuth 或用于多用户部署的按请求远程认证。
多种传输方式	stdio 用于本地客户端，SSE 用于旧客户端，可流式 HTTP 用于远程部署。
客户端友好的设置	为 Claude Code、Codex、Cursor、VS Code、Copilot 和通用基于 JSON 的 MCP 客户端提供现成的安装命令。
自托管就绪	适用于自定义 GitLab URL、代理设置，并且可以从 Docker、Homebrew、npm 或 Nix 运行。
JMESPath 过滤	工具 JSON 结果的可选后处理，以缩小负载，而无需更改底层 GitLab 请求。
权限模式	`readonly`、`modify`（无破坏性删除）或 `full` – 按工具和工具集强制执行。
结果压缩	过大的工具回复可以被截断，并提供预览和 CLI 命令来获取完整数据。
掩码支持	对隐私敏感字段进行文本响应掩码。

如何运行

安装 – 通过 npm（npm i -g @zereight/mcp-gitlab）、Homebrew（brew tap zereight/gitlab-mcp && brew install zereight-mcp-gitlab）或 Nix（将 flake 添加为输入）。
提供令牌 – 设置 GITLAB_PERSONAL_ACCESS_TOKEN（或 _FILE 变体）或使用 zereight-mcp-gitlab auth 运行内置的 OAuth 设备流程。
启动服务器 – 只需运行 zereight-mcp-gitlab。默认情况下，它将监听 0.0.0.0:3002。

配置您的 MCP 客户端 – 例如，对于 Claude Code：

claude mcp add gitlab \
  --transport stdio \
  --scope local \
  --env GITLAB_PERSONAL_ACCESS_TOKEN="$GITLAB_PERSONAL_ACCESS_TOKEN" \
  --env GITLAB_API_URL=https://gitlab.com/api/v4 \
  -- zereight-mcp-gitlab

类似片段适用于 VS Code、Cursor、Copilot 和通用基于 JSON 的客户端。

何时使用？

AI 增强开发 – 让 LLM 创建分支、打开合并请求、运行 CI 或获取问题数据，而无需编写自定义 API 调用。
多用户 AI 助手 – 远程认证模式允许每个用户呈现自己的 PAT，从而实现尊重个人权限的共享服务器。
自托管 GitLab – 服务器可以指向任何 GitLab 实例（GITLAB_API_URL），使其适用于内部企业。
实验 – 因为工具集是可扩展的（discover_tools），您可以在不修改服务器代码的情况下原型化新的 GitLab 相关操作。

最有用的 CLI 标志快速参考

标志	用途
`--token <PAT>`	覆盖环境变量中的个人访问令牌。
`--api-url <URL>`	将服务器指向自定义 GitLab API 端点。
`--permission-mode <readonly	modify
`--toolsets <list>`	启用命名工具组（例如 `core,wiki,milestones`）。
`--tools <tool1,tool2>`	在默认集之上添加单个工具。
`--use-wiki`、`--use-milestone`、`--use-pipeline`	旧标志（已弃用），启用相应的工具集。
`--compact-results`	截断大型工具响应，并提供 CLI 命令获取完整负载。
`--masking-enabled`	为隐私敏感字段启用响应掩码。

了解更多

文档站点 – https://zereight.github.io/gitlab-mcp/（完整指南、工具参考、认证详情）。
比较图表 – 显示此服务器与社区风格的 GitLab MCP A 和官方 GitLab MCP 服务器的区别。
技能文件 – skills/gitlab-mcp/ 包含帮助 LLM 正确使用工具的提示片段。

TL;DR

gitlab-mcp 是一个专门构建的 MCP 服务器，将 GitLab 变成 AI 代理的丰富工具箱。安装二进制文件，给它一个令牌，启动它，并将您的 LLM 驱动的客户端指向它 – 您将立即通过一个简单、权限感知的 API 获得数百个 GitLab 操作（问题、MR 差异、流水线、维基、发布等）。