GitLab MCP

GitLab MCP 是一个与 harness 无关的 Model Context Protocol 服务器，外加用于 GitLab 仓库工作的共享 Agent Skills。Codex、Claude Code、Cline 和 Pi 是同一规范 MCP 核心的支持发行版，而不是独立的 GitLab 实现。ChatGPT 可以通过远程 Streamable HTTP 部署使用同一核心。

该项目提供：

• 一个自带类型的 GitLab MCP 服务器；

• 一个通用的 $gitlab skill；

• 用于未解决合并请求讨论的 $gl-address-comments；

• 用于流水线和作业诊断的 $gl-fix-ci；

• 用于分支、提交、推送和草稿 MR 交付的 $gl-publish；

• GitLab 原生的 runner、CI lint、治理、标签、发布和流水线计划工作流，以及安全可靠的项目和组 CI/CD 变量管理；

• 精简的 Codex、Claude Code、Cline 和 Pi 发行版，复用相同的规范核心和 Agent Skills；以及

• 用于 ChatGPT 部署的无状态 Streamable HTTP 传输和 OAuth 受保护资源元数据。

从这里开始

文档索引 链接了完整的用户、运维、开发者、安全、兼容性和发布文档集。

Related MCP server: GitLab MCP Server

快速开始

对于本地源码安装，请使用 Node.js 22 或更高版本，然后构建并验证规范 MCP 核心：

npm.cmd ci
npm.cmd test
npm.cmd run build

选择与 harness 匹配的适配器。所有四个受支持的适配器都使用相同的已构建 MCP 包和规范 Agent Skills。

对于 Codex，将此仓库添加到受信任的本地 marketplace，安装 gitlab 插件，然后重启或刷新 Codex。已建立的根 Codex 清单 .mcp.json、预加载和工件名称仍然是受支持的兼容性表面。在启动 Codex 的环境中配置 GitLab 实例和令牌：

$env:GITLAB_URL = "https://gitlab.example.com"
$env:GITLAB_TOKEN = "<token>"

开始新对话并要求 Codex 确认连接，例如：

Use GitLab to tell me which account and instance are connected.

Claude Code 用户可以加载物化的原生插件发行版，该发行版捆绑了相同的 MCP 服务器和规范 Agent Skills。有关包验证、--plugin-dir 加载和 marketplace 兼容布局，请参阅 Claude Code 适配器指南。

Cline 用户可以通过 stdio 使用相同的规范 MCP 包，并安装规范 Agent Skills，而无需单独的 GitLab 实现。有关 IDE 和 CLI 设置，请参阅 Cline 适配器指南。

Pi 用户可以通过精简的 stdio 桥接安装专用的 Pi 包，该包注册规范 MCP 工具清单并公开相同的 Agent Skills。有关包安装、运行时依赖处理和桥接限制，请参阅 Pi 适配器指南。

有关最小权限令牌指南、常见 GitLab 工作流和 ChatGPT HTTP 部署，请参阅 用户指南。

要求

• Node.js 22 或更高版本

• GitLab.com、GitLab Dedicated 或自管理 GitLab 实例

• 对于本地 stdio 使用，需要具有你打算执行的操作所需的最小范围的 GitLab 令牌

构建和验证

npm.cmd install
npm.cmd test
npm.cmd run adapters:check
npm.cmd run check:bundle
npm.cmd run build
npm.cmd run validate:codex
npm.cmd run validate:claude
npm.cmd run validate:cline
npm.cmd run validate:pi
npm.cmd run check:versions
npm.cmd run check:gitlab-oauth -- https://gitlab.example.com

规范 MCP 包路径由 distribution.json 定义；当前配置构建 server/dist/gitlab-mcp.cjs。MCP 包本身在源码控制中生成并被忽略，然后包含在发布工件中。Harness 包仍可声明 harness 侧运行时依赖；例如，Pi 包使用 MCP SDK 将 Pi 桥接到该捆绑服务器。

distribution.json 是共享分发元数据的权威来源，包括中性的 gitlab 分发标识符、基础版本、描述、许可证、规范 MCP 包和 Skills 路径。更改后，运行 npm run adapters:generate 并审查生成的 Codex/Claude Code/Cline/Pi 元数据。npm run adapters:check 会拒绝元数据漂移以及缺失、非目录或逃逸仓库的规范 Skills 路径。

npm run check:bundle 执行内存中的干净构建，如果规范包包含 harness 特定的实现引用，则失败。npm run check:versions 验证生成的包和 Codex 发布元数据与 distribution.json 保持一致。Codex 插件清单可以在 + 后附加 Codex 构建元数据，而无需更改该基础分发版本。SERVER_VERSION 由与 harness 无关的 MCP 核心独立拥有，仅当核心运行时本身发生变化时才递增。

与 harness 无关的核心和适配器边界记录在 ADR-001 中。GEN-08 聚焦审计和身份决策记录在 docs/GENERALISATION_AUDIT.md 中。

持续集成

GitLab 合并请求、默认分支和标签流水线运行语法检查、测试、覆盖率、dependency-cruiser、格式化/代码风格检查、生产依赖审计、干净包构建以及捆绑的 stdio/HTTP 冒烟测试。GitLab SAST 和 secret-detection 模板也已启用。Codex、Claude Code、Cline 和 Pi 在规范构建后各有聚焦的适配器验证；这些作业验证 harness 打包和 MCP 启动，而不重复核心 Node/安全矩阵。

标签流水线还发布确定性的 Codex 归档及其 CycloneDX SBOM 和 SHA256SUMS，以及可重现的 Claude Code、Cline 和 Pi MCP + Skills 归档及匹配的 .sha256 侧车文件，作为 GitLab 作业工件。最终发布集门要求恰好四个受支持的 harness，并比较它们的规范 MCP 包和 Skills 摘要。在根据 docs/PUBLICATION_CHECKLIST.md 验证工件之前，发布不被视为完成。

已提交的 docs/gitlab-tool-contracts.json 清单使用边界有效输入调用每个已注册工具，并锁定其安全分类、HTTP 方法、编码路由、查询/主体映射和有界响应模式。覆盖率覆盖每个生产源码模块，低于 90% 行、80% 函数或 75% 分支则失败；添加没有清单条目的工具会导致测试失败。

语法和测试作业在 node:22-alpine 和 node:24-alpine 上运行；阈值强制覆盖率作业在 Node 22 上运行。核心作业需要能够运行这些镜像并访问 npm 注册表的未标记 Linux runner。安全模板从 GitLab 注册表拉取其分析器镜像。核心 Node.js 作业不需要特权模式。配置至少一个接受未标记作业并允许作业在合并前成功流水线运行至少 10 分钟的项目、组或实例 runner。

本地 Codex 身份验证

在启动 Codex 的环境中设置实例 URL 和令牌：

$env:GITLAB_URL = "https://gitlab.example.com"
$env:GITLAB_TOKEN = "<token>"

GITLAB_URL 默认必须使用 HTTPS，并拒绝嵌入的凭据、查询和片段。对于无法使用 TLS 的显式本地/私有开发 GitLab 实例，设置 GITLAB_ALLOW_INSECURE_HTTP=true。该覆盖在生产环境和公共主机名中被拒绝；它接受回环、私有网络 IP、单标签主机以及私有开发后缀 .localhost、.local、.internal 和 .home.arpa。

GITLAB_URL 默认为 https://gitlab.com。Codex .mcp.json 通过 stdio 启动捆绑服务器，并在与 harness 无关的核心之前加载精简的 Codex 分发适配器。令牌在运行时读取，永远不会存储在分发中。

使用覆盖任务所需的最窄令牌范围。只读工作可以使用面向读取的令牌；仓库、问题、合并请求或 CI 变更需要相应的 GitLab API 权限。

能力发现

在诊断 GitLab 操作是不受支持、未许可、禁用还是仅对当前凭据不可访问之前，调用 get_gitlab_capabilities。它仅使用对 /user、/version、/metadata、/personal_access_tokens/self 以及（当凭据不是个人访问令牌时）/oauth/token/info 的只读请求。OAuth 诊断报告范围和剩余生命周期，但绝不暴露令牌或 OAuth 应用程序标识符。GitLab 可能隐藏或省略这些端点，尤其是在较旧的自管理版本或非管理员用户中，因此模糊结果报告为 unknown 而不是猜测。

每个能力是 available、unavailable、permission_required、license_required、not_configured 或 unknown 之一，并附有简洁的原因和有用的支持证据。传递 detailed: true 以获取规范化的每次探测结果，或传递 refresh: true 以绕过缓存。

结果按规范化的实例 URL 和经过身份验证的凭据身份缓存 60 秒。缓存键包含单向 SHA-256 摘要，绝不包含原始 bearer 令牌。条目在 60 秒后过期，由 refresh 绕过，并自然分离实例或更改的凭据。过期的条目会被机会性地移除，256 条目 LRU 限制提供硬内存边界。缓存仅存在于内存中，并在 MCP 服务器进程重启时清除。

HTTP 服务器

对于本地开发：

$env:MCP_PUBLIC_URL = "https://mcp.example.com/mcp"
$env:GITLAB_URL = "https://gitlab.example.com"
npm.cmd run start:http

HTTP 模式要求每个 /mcp 请求都带有 bearer 令牌。服务器端令牌默认禁用。ALLOW_SERVER_TOKEN_HTTP=true 仅用于受控的私有测试，不应用于共享部署。

设置 MCP_READ_ONLY=true 以进行仅检查部署。在该模式下，服务器仅注册标记为只读的工具，并通告 GitLab 的 read_api OAuth 范围。默认的写启用模式暴露完整的工具集并要求 api。服务器在注册期间验证每个工具注释，因此未分类或变更工具不能静默进入只读表面。

当绑定到 IPv4 通配符 0.0.0.0 或 IPv6 通配符 :: 时，请将 MCP_ALLOWED_HOSTS 设置为逗号分隔的公共主机名允许列表。将服务置于 HTTPS 之后，并将 MCP_PUBLIC_URL 设置为其规范的公共 /mcp URL。生产模式要求提供 MCP_PUBLIC_URL，拒绝嵌入的凭据、查询、片段以及非 /mcp 路径，并且要求使用 HTTPS。MCP_ALLOW_INSECURE_PUBLIC_URL=true 仅可用于在回环监听器上进行显式的本地开发，在生产环境或公共主机上会被拒绝。ALLOW_SERVER_TOKEN_HTTP=true 同样仅限于回环私有测试，不得用于共享部署。

在安装或部署后，使用只读的 get_runtime_info 工具来确认核心/发行版本、部署模式、只读过滤，以及已注册工具清单的确定性 SHA-256 指纹。

HTTP MCP 请求体默认限制为 8 MiB。这既容纳了有界的多文件提交和其他合法的大型工具负载，又防止了无限制的请求缓冲。将 MCP_MAX_REQUEST_BYTES 设置为 65,536 到 26,214,400 字节之间的整数，以使用不同的部署限制。服务器前方的任何反向代理都必须至少允许相同大小的请求。

长期运行的 HTTP 部署还会对身份验证和请求状态进行限制：

• MCP_TOKEN_CACHE_MAX_ENTRIES 限制已验证的 bearer 身份，默认 256，带有 60 秒 TTL 和 LRU 逐出；

• MCP_AUTH_FAILURE_LIMIT 限制每个直接连接的地址在 MCP_AUTH_FAILURE_WINDOW_MS 内被拒绝的令牌数量，默认每 60 秒 20 次失败；

• MCP_AUTH_FAILURE_MAX_ENTRIES 限制失败跟踪状态，默认 1,024；

• MCP_MAX_CONCURRENT_REQUESTS 限制活动的 MCP 请求数，默认 32；以及

• MCP_MAX_CONCURRENT_REQUESTS_PER_IDENTITY 限制单个已验证 GitLab 用户的请求数，默认 4。

在 TLS 反向代理处配置补充性的速率和连接限制。该应用故意使用直接对端地址，而不是默认信任转发的标头，因此应在流量到达此服务之前应用代理级别的客户端 IP 限制。

未经身份验证的 /health 端点是一个与拓扑无关的进程存活检查。/ready 是一个单独的就绪检查，当其依赖探针不可用时返回 503。每个响应都包含一个生成的 X-Request-Id；内部 MCP 故障仅记录该标识符和错误类型。嵌入方可以提供用于指标观测的请求完成观察器，而无需接收 bearer 令牌或请求负载。

部署后，请验证公共资源元数据以及两种健康检查语义：

npm.cmd run check:mcp-deployment -- https://mcp.example.com/mcp

安全模型

• 工具会声明只读、写入和破坏性注解。

• create_commit 仅支持非破坏性文件操作；删除和强制提交更新需要单独注解且带有并发安全字段的 create_destructive_commit 工具。

• GitLab 响应体（包括作业日志、制品和 API 错误）在严格的字节限制下进行流式传输，并且仍受请求超时限制；

• API 错误会被规范化，不会回显凭据；

• 能力发现会对错误证据进行脱敏，且从不读取私有 CI 变量或变更端点；

• HTTP bearer 令牌会根据配置的 GitLab 实例进行验证，并通过单向令牌哈希缓存在有界的 TTL/LRU 缓存中；

• 被拒绝的凭据和并发请求受到限制，且不会记录令牌或私有身份详细信息；

• HTTP 模式会使用受保护资源元数据对未经身份验证的请求进行质询；

• HTTP 工具会公布每个工具的 OAuth 或私有服务器令牌安全方案，以及模型可见的重新授权质询；以及

• 技能要求对合并、审批、删除、讨论解决和 CI 状态变更具有明确意图。

许可证

MIT