MCP Gitlab Server

GitLab MCP服务器

The most comprehensive Model Context Protocol (MCP) server for GitLab — 86 tools, enterprise-ready, actively maintained.

______________________________________________________________________

这是什么

GitLab MCP服务器允许AI代理（Claude Desktop、Claude Code、Cursor、Zed、VS Code或任何 模型上下文协议 客户端）直接与GitLab对话。它是一个类型化的、分页的、经过架构验证的到GitLab REST API的桥，公开为86个MCP工具。它不是一个包装 glab 并且它不会刮屏。

它与 gitlab.com 或任何自托管的GitLab实例，并使用个人访问令牌、上游网关转发的OAuth承载令牌或用于安全演示的只读令牌进行身份验证。

______________________________________________________________________

为什么它存在

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图表。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.

远程（流式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 per connection——服务器将该Bearer作为per connection PAT转发给GitLab。将客户指向 http://your-gateway/mcp.

操作细节、探头配置和故障排除见 docs/OPERATIONS.md.

______________________________________________________________________

盒子里有什么

86个工具，按表面分组：

• 存储库：搜索、创建、分叉、获取和更新项目元数据。
• 文件和分支：读取、创建、更新和删除文件；多文件提交；分支（列出、创建、删除）；存储库树。
• 标签和发布：列出并创建标签；列出并创建发布。
• 问题：创建、列表、更新、注释、线程讨论。
• 合并请求：创建、更新、合并、重基；批准；自动合并；笔记、讨论、更改、提交。
• CI/CD：管道（列表、获取、触发、重试、取消）、作业（列表、获得、日志、重试、删除）、环境。
• Wiki：项目和组Wiki，包括附件。
• 组和成员：组CRUD、子组、项目和组成员。
• 标签和里程碑：列表、创建、更新；受保护的分支：列表、保护、取消保护。
• 用户和元：当前用户、列表/获取用户、项目事件、提交历史。

中的完整工具列表 CLAUDE.md。中所选工具的每个工具文档 docs/api/.

只读模式(GITLAB_READ_ONLY_MODE=true)在注册时过滤掉每个变异工具。行为不端的特工看不见他们，更不用说给他们打电话了。

______________________________________________________________________

运输

流式HTTP运行 POST /mcp, GET /mcp，以及 DELETE /mcp，通过会话管理 MCP-Session-Id 头球这 /healthz 当活动会话超过时，端点返回503 HEALTHZ_MAX_SESSIONS，用于Kubernetes活性和就绪性探测。

______________________________________________________________________

认证

两种模式。正确的方法取决于HTTP传输是否可以从网络访问。

每个连接的OAuth(AUTH_MODE=oauth，网络公开部署的默认设置）。服务器没有静态令牌。每个MCP连接都有自己的 Authorization: Bearer ，服务器将其作为该连接的有效PAT转发给GitLab。在处理IdP的网关后面运行它。这就是如何为整个团队操作一个共享部署。只要绑定是非环回的，就需要。

PAT模式(AUTH_MODE=pat，仅限环回）。服务器在中持有一个个人访问令牌 GITLAB_PERSONAL_ACCESS_TOKENHTTP传输正在运行 无身份验证 在这种模式下，服务器强制执行仅环回绑定(HOST=127.0.0.1)并拒绝以其他方式开始。stdio客户端和单租户本地开发的正确选择。Helm不支持——请参阅图表的身份验证保护。

______________________________________________________________________

配置

.env.example 在回购中为当地发展提供资金。

______________________________________________________________________

部署

码头工人

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

多阶段构建 node:24-alpine.以非root（uid 1000）身份运行，所有功能均已删除。与只读根文件系统和 seccompProfile: RuntimeDefault Kubernetes pod安全设置。发布时，图片标签跟在semver后面； latest 跟踪最新标记的版本。

Kubernetes（Helm）

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

图表默认为 AUTH_MODE=oauth 因此，vanilla安装是身份验证门控的。使用注入的Ingress或网关来提供服务 Authorization: Bearer 每个连接。

该图表将活体和准备状态探测器运送到 /healthz，可选 PodDisruptionBudget、带有滚动重启注释的ConfigMap和Secret，以及五个拒绝呈现错误配置的故障大声防护：

• AUTH_MODE=pat 无环回 HOST （CWE-306——见 chart/templates/auth-validation.yaml)
• PAT模式下的空PAT existingSecret
• 两者 existingSecret 和内联 secret.GITLAB_PERSONAL_ACCESS_TOKEN set（否则为无声优先级陷阱）
• PDB minAvailable >= replicaCount （排水死锁）
• 两者 minAvailable 和 maxUnavailable 在PDB上设置（Kubernetes在准入时拒绝此组合）

values.yaml 注释为 helm-docs，以及 chart/README.md 在CI中重新生成并检查漂移。

______________________________________________________________________

安全

关于供应链，有几件事是正确的。每个npm发布都用 Sigstore来源 通过OIDC可信出版。CodeQL在每次推送和PR上运行 security-extended 和 security-and-quality 查询包。Dependabot是打开的、分组的和每周的。 npm audit 报告当前版本中没有漏洞。 main 需要PR、状态检查、挤压或重基合并以及线性历史记录。

只读模式在工具注册时强制执行，而不是在请求边界。如果回归允许写工具在以下条件下执行 GITLAB_READ_ONLY_MODE=true，这是一个安全漏洞。请报告。

______________________________________________________________________

这在生态系统中的位置

有几种方法可以将GitLab和MCP结合起来。选择一个符合你情况的：

• GitLab内置的MCP服务器 在 https:///api/v4/mcp.15工具，需要GitLab Premium或Ultimate，OAuth与您的GitLab IdP集成。如果您有订阅和15个工具，那么正确的选择对您的代理商来说是足够的表面积。
• 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图表。如果你想要一个规模较小、安全性成熟的项目，可以干净利落地部署到Kubernetes中，那就太好了。

这些都不是普遍最好的，我们也不会假装不是。

______________________________________________________________________

贡献

PR欢迎。我们要求的形状：

1. 叉子、树枝(feature/*, fix/*, docs/*, refactor/*).
2. 常规承诺(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_code_of_conduct.md.行为准则： CODE_OF_CONDUCT.md.一些 good first issue 门票在问题跟踪器中实时显示。

______________________________________________________________________

贡献者

这个项目的作者比它的起源所暗示的要多。

扬（纳莱克）平静 是原作者和维护者。Yoda Digital首席技术官。

奥利维耶·金特兰德（@ecthelion77） 编写了每个连接的OAuth身份验证路径、MCP流式HTTP传输、多级Dockerfile和Helm图表，包括故障大声防护。版本0.4.0和0.5.0主要是他的作品，通过PR#42和PR#44合并。

Dependabot负责更改日志中的大部分杂务提交，并且从不睡觉。

如果你已经发送了PR或安全报告，但你不在这个列表中，那就是一个bug。请打开一个问题。

______________________________________________________________________

许可证

麻省理工学院.

______________________________________________________________________

链接

• Yoda Digital开源门户
• 更新日志
• 操作指南
• 光标集成
• 安全策略
• 行为准则
• MCP规范

______________________________________________________________________

建于❤️ 通过 尤达。数字