GitLab MCP Server

GitLab MCP 服务

最全面的 GitLab 模型上下文协议（MCP）服务——提供 86 个工具，适用于企业，持续积极维护。

---

项目介绍

GitLab MCP Server 可让 AI Agent（Claude Desktop、Claude Code、Cursor、Zed、VS Code，或任何 模型上下文协议客户端）直接与 GitLab 通信。它是一个类型化、支持分页且经过架构验证的 GitLab REST API 桥接层，以 86 个 MCP 工具的形式提供。它并非对 glab 的封装，也不会抓取网页内容。

它既可连接 gitlab.com，也可连接任何可自托管的 GitLab 实例，并支持使用个人访问令牌、由上游网关转发的 OAuth Bearer 令牌，或用于安全演示的只读令牌进行身份验证。

---

项目缘起

Anthropic 于 2024 年 11 月 25 日发布了 MCP。参考服务覆盖了 Google Drive、Slack、GitHub、Git、Postgres 和 Puppeteer，但当时没有 GitLab 服务。Yoda Digital 工程团队使用可自托管的 GitLab，因此官方示例对我们没有帮助，而早期的社区移植项目还没有尝试妥善覆盖 GitLab 的功能范围。

于是我们为自己开发了一个。它涵盖了群组项目、活动跟踪，以及 DevOps 团队实际需要的操作。我们于 2025 年 3 月 18 日将其开源，原以为可能只有五个人会觉得它有用。

一年后，这个项目已有 86 个工具，支持 stdio / SSE / Streamable HTTP 传输、PAT 和 OAuth 模式、托管在 ghcr.io 上的 Docker 镜像，以及一个几乎完全由我们素未谋面的外部贡献者编写的 Helm chart。如今 0.4.0 和 0.5.0 版本的代码大多出自他人之手——这正是开源维护者最乐见的问题。

---

快速开始

本地客户端（stdio）

适用于 Claude Desktop、Cursor、Zed，以及任何将 MCP 服务作为本地子进程运行的客户端。将以下内容添加到客户端的 MCP 配置中（Claude Desktop 的配置文件为 claude_desktop_config.json）：

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@yoda.digital/gitlab-mcp-server"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-…",
        "GITLAB_API_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}

使用可自托管实例？将 GITLAB_API_URL 替换为你的实例地址，例如 https://gitlab.example.com/api/v4。想要进行不具备写入权限的安全演示？添加 "GITLAB_READ_ONLY_MODE": "true"。各 IDE 的说明见 docs/CURSOR_INTEGRATION.md。

远程（Streamable HTTP，由 OAuth 保护）

对于共享部署和新式远程 MCP 客户端，可将服务作为 HTTP 服务运行。对外暴露到网络的部署必须设置 AUTH_MODE=oauth——如果绑定到非回环地址，服务会拒绝以 AUTH_MODE=pat 启动。威胁模型请参阅 SECURITY.md。

docker run --rm -p 3000:3000 \
  -e HOST=0.0.0.0 \
  -e AUTH_MODE=oauth \
  -e USE_STREAMABLE_HTTP=true \
  ghcr.io/yoda-digital/mcp-gitlab-server:latest

然后在容器前部署一个网关，为每个连接注入 Authorization: Bearer <token>——服务会将该 Bearer 转发给 GitLab，作为每个连接的 PAT。将客户端指向 http://your-gateway/mcp。

运维详情、探针配置和故障排除请参阅 docs/OPERATIONS.md。

---

包含内容

共 86 个工具，按类别分组：

• 仓库：搜索、创建、派生、获取和更新项目元数据。
• 文件和分支：读取、创建、更新和删除文件；多文件提交；分支（列出、创建、删除）；仓库树。
• 标签和发布：列出和创建标签；列出和创建发布。
• Issue：创建、列出、更新、备注、线程讨论。
• 合并请求：创建、更新、合并、变基；审批；自动合并；备注、讨论、变更、提交。
• CI/CD：流水线（列出、获取、触发、重试、取消）、作业（列出、获取、日志、重试、取消）、环境。
• Wiki：项目和群组 Wiki，包括附件。
• 群组和成员：群组 CRUD、子群组、项目和群组成员。
• 标签和里程碑：列出、创建、更新；受保护分支：列出、保护、取消保护。
• 用户和元数据：当前用户、列出/获取用户、项目事件、提交历史。

完整工具列表请参阅 CLAUDE.md。部分工具的文档请参阅 docs/api/。

只读模式（GITLAB_READ_ONLY_MODE=true）会在注册时过滤掉所有会修改数据的工具。行为异常的 Agent 既看不到这些工具，更无法调用它们。

---

传输方式

传输方式	使用场景	标志
stdio	本地客户端（Claude Desktop、Cursor、Zed）。默认方式。	(默认)
SSE	仍使用旧版 SSE 规范的远程客户端。	USE_SSE=true
Streamable HTTP	使用当前 MCP Streamable HTTP 规范的远程客户端。	USE_STREAMABLE_HTTP=true

Streamable HTTP 会运行 POST /mcp、GET /mcp 和 DELETE /mcp，并通过 MCP-Session-Id 标头管理会话。当活跃会话数超过 HEALTHZ_MAX_SESSIONS 时，/healthz 端点会返回 503，供 Kubernetes 存活和就绪探针使用。

---

身份验证

有两种模式。选择哪种模式取决于 HTTP 传输是否可从网络访问。

按连接使用 OAuth（AUTH_MODE=oauth，对外暴露到网络的部署默认采用此模式）。服务不持有静态令牌。每个 MCP 连接都携带自己的 Authorization: Bearer <token>，服务会将其转发给 GitLab，作为该连接的有效 PAT。将服务部署在负责处理 IdP 的网关后。这种方式适合为整个团队运行一个共享部署。绑定到非回环地址时必须使用此模式。

PAT 模式（AUTH_MODE=pat，仅限回环地址）。服务会在 GITLAB_PERSONAL_ACCESS_TOKEN 中持有一个个人访问令牌。此模式下，HTTP 传输不进行身份验证，因此服务会强制要求仅绑定到回环地址（HOST=127.0.0.1），否则拒绝启动。适用于 stdio 客户端和单租户本地开发。Helm 不支持此模式——请参阅 Chart 的身份验证验证保护机制。

---

配置

变量	默认值	用途
GITLAB_PERSONAL_ACCESS_TOKEN	—	PAT 模式下必需。
GITLAB_API_URL	https://gitlab.com/api/v4	GitLab API 基础 URL。如有需要，可指向自托管实例。
GITLAB_READ_ONLY_MODE	false	隐藏所有写入工具。
AUTH_MODE	pat	pat（仅限回环地址）或 oauth（任意绑定地址）。
HOST	127.0.0.1	HTTP 传输的绑定地址。设置为 0.0.0.0 可向网络开放，但仅限 AUTH_MODE=oauth；否则启动会被拒绝。
USE_SSE	false	启用旧版 SSE 传输。
USE_STREAMABLE_HTTP	false	启用 MCP Streamable HTTP 传输。
PORT	3000	SSE 和 Streamable HTTP 的 HTTP 监听端口。
CORS_ALLOW_ORIGINS	(empty)	以逗号分隔的允许列表。PAT 回环模式下留空表示 *（仅限本地开发）；OAuth 模式下留空表示拒绝。绑定到非回环地址时绝不会返回通配符。
HEALTHZ_MAX_SESSIONS	10000	超过此阈值时，/healthz 会返回 503。

仓库中提供了 .env.example，供本地开发使用。

---

部署

Docker

ghcr.io/yoda-digital/mcp-gitlab-server:latest

基于 node:24-alpine 的多阶段构建。以非 root 用户（uid 1000）运行，并移除所有能力。兼容只读根文件系统和 Kubernetes Pod 安全设置 seccompProfile: RuntimeDefault。镜像标签在发布时遵循 semver；latest 始终指向最近标记的版本。

Kubernetes（Helm）

helm install gitlab-mcp oci://ghcr.io/yoda-digital/charts/gitlab-mcp

Chart 默认使用 AUTH_MODE=oauth，因此普通安装会启用身份验证。请使用注入 Authorization: Bearer <token> 的 Ingress 或网关，为每个连接提供令牌，并将 Service 放在其后。

Chart 提供针对 /healthz 的存活和就绪探针、可选的 PodDisruptionBudget、带有滚动重启注解的 ConfigMap 和 Secret，以及五项会在配置错误时拒绝渲染的保护措施：

• AUTH_MODE=pat 且 HOST 为非回环地址（CWE-306 — 参见 chart/templates/auth-validation.yaml）
• PAT 模式下 PAT 为空，且未设置 existingSecret
• 同时设置了 existingSecret 和内联的 secret.GITLAB_PERSONAL_ACCESS_TOKEN（否则会造成不易察觉的优先级问题）
• PDB minAvailable >= replicaCount（排空死锁）
• 在 PDB 上同时设置 minAvailable 和 maxUnavailable（Kubernetes 会在准入阶段拒绝这种组合）

values.yaml 已添加 helm-docs 注解，chart/README.md 会重新生成，并在 CI 中检查是否存在差异。

---

安全

请通过 GitHub 的私密漏洞报告报告漏洞，而不要在公开问题中提交。威胁模型和范围见 SECURITY.md。

供应链方面有几点事实：每次 npm 发布都会通过 OIDC Trusted Publishing 使用 Sigstore provenance 签名。CodeQL 会在每次推送和 PR 时运行，并启用 security-extended 和 security-and-quality 查询包。Dependabot 已启用，按组配置并每周运行。当前版本的 npm audit 报告零个漏洞。main 分支要求通过 PR 合并、通过状态检查、使用 squash 或 rebase 合并，并保持线性历史。

只读模式是在工具注册时强制执行，而不是在请求入口处执行。如果发生回归，导致写入工具在 GITLAB_READ_ONLY_MODE=true 时执行，这属于安全漏洞。请报告此问题。

---

它在生态系统中的定位

将 GitLab 与 MCP 结合的方式有好几种。请选择适合你情况的一种：

• GitLab 自带的 MCP 服务，地址为 https://<your-instance>/api/v4/mcp。提供 15 个工具，需要 GitLab Premium 或 Ultimate，并通过 GitLab IdP 集成 OAuth。如果你拥有相应订阅，且 15 个工具足以满足 Agent 的需求，这是合适的选择。
• zereight/gitlab-mcp，规模最大的社区实现。认证方式更丰富（PAT、OAuth2 浏览器流程、OAuth 代理、远程授权），工具也更多。如果你希望覆盖范围最大，且不介意理解一个规模更大的项目，这是不错的选择。
• mcpland/gitlab-mcp，专注于策略引擎。支持 OAuth2 PKCE、多实例路由、基于 Cookie 的认证。适用于需要严格管控的企业部署。
• 本服务（@yoda.digital/gitlab-mcp-server）。提供 86 个工具、三种传输方式、PAT 和 OAuth、具有 Sigstore 来源证明的 npm 发布包、以非 root 用户运行的多阶段 Docker 镜像，以及带有故障时明确报错保护机制的 Helm chart。适合希望采用规模较小、安全成熟的项目，并顺畅部署到 Kubernetes 的场景。

没有哪一种放之四海而皆准，我们不会假装事实如此。

---

参与贡献

欢迎提交 PR。我们对贡献的要求如下：

1. Fork 仓库并创建分支（feature/*、fix/*、docs/*、refactor/*）。
2. 使用 Conventional Commits（feat:、fix:、docs:、chore: 等）。它们用于生成变更日志。
3. 如果行为有变化，请添加或更新 vitest 测试。npm test 是必过检查。
4. 提交 PR。CI 会运行 build-and-test、CodeQL、Dockerfile lint、Helm lint 和模板冒烟测试，以及 Helm chart README 漂移检查。

本地设置：

git clone https://github.com/yoda-digital/mcp-gitlab-server.git
cd mcp-gitlab-server
npm install
npm test
npm run dev

完整指南见 CONTRIBUTING.md。AI 辅助贡献规则见 ai_code_of_conduct.md。行为准则见 CODE_OF_CONDUCT.md。问题跟踪器中还有一些 good first issue 工单。

---

贡献者

本项目的作者比其起源所显示的更多。

Ion (Nalyk) Calmîș 是原作者和维护者，也是 Yoda Digital 的 CTO。

Olivier Gintrand (@ecthelion77) 编写了 OAuth 连接级认证流程、MCP Streamable HTTP 传输、多阶段 Dockerfile 和 Helm chart（包括故障时明确报错的保护机制）。0.4.0 和 0.5.0 版本的发布工作主要由他完成，并通过 PR #42 和 PR #44 合并。

Thomas Léveil (@thomasleveil) 和 BenSchoweCONPORT 提交了早期 PR。

Dependabot 负责变更日志中的大部分例行维护提交，而且从不休息。

如果你提交过 PR 或安全报告，但不在此名单中，那就是个错误。请提交 issue。

---

许可证

MIT。

---

链接

• npm 包
• Yoda Digital 开源门户
• 变更日志
• 运维指南
• Cursor 集成
• 安全策略
• 行为准则
• MCP 规范

---

由 Yoda.Digital 倾心打造 ❤️