GitLab MCP Server

GitLab MCP 服务

English | 한국어 | 简体中文 | Português (Brasil)

📖 文档 → · llms.txt · llms-full.txt

默认：40 个工具（38 个 core + discover_tools + help）。总共有 278 个工具（工具集中的 275 个 + execute_graphql + discover_tools + help）。从精简配置开始；调用 discover_tools，即可在本次会话中启用更多工具。

首先使用 npm install -g @zereight/mcp-gitlab 安装 zereight-mcp-gitlab 二进制文件，或使用 Homebrew 执行 brew tap zereight/gitlab-mcp https://github.com/zereight/gitlab-mcp 和 brew install zereight/gitlab-mcp/zereight-mcp-gitlab。官方 MCP Registry 列表：io.github.zereight/gitlab-mcp。一行命令：npx -y @zereight/mcp-gitlab@latest。

无此 MCP → 使用此 MCP

无此 MCP	使用此 MCP
将 MR URL 和差异内容粘贴到聊天中	list_merge_request_changed_files → 批量调用 get_merge_request_file_diff
在 GitLab UI 中查找作业日志	使用分页功能调用 get_pipeline_job_output
每轮都重新说明项目路径	project_id=group%2Fproject 和 merge_request_iid=123

三种安装方式

方式	适用场景	方法
本地 IDE	在你的计算机上使用 Cursor、Claude Code、Codex	stdio + PAT 或本地 OAuth
共享 HTTP	团队或托管的 MCP	Streamable HTTP URL + 远程身份验证或 MCP OAuth
Claude.ai	Claude 网页连接器	公共 HTTPS + GITLAB_MCP_OAUTH

安装

首先安装二进制文件（npm install -g @zereight/mcp-gitlab，或使用 Homebrew 执行 brew tap zereight/gitlab-mcp https://github.com/zereight/gitlab-mcp，然后执行 brew install zereight/gitlab-mcp/zereight-mcp-gitlab）。读取令牌时不回显：

read -rs GITLAB_PERSONAL_ACCESS_TOKEN && export GITLAB_PERSONAL_ACCESS_TOKEN

# 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

# Codex
codex mcp add gitlab --env GITLAB_PERSONAL_ACCESS_TOKEN="$GITLAB_PERSONAL_ACCESS_TOKEN" --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab

其他客户端：VS Code · GitHub Copilot · JSON 客户端 · Cursor 详细说明

Agent 粘贴提示词

将以下内容复制到能够编辑 MCP 配置的 Agent 中：

Install the GitLab MCP server (@zereight/mcp-gitlab) for this workspace.
Binary: zereight-mcp-gitlab (npm i -g @zereight/mcp-gitlab, or npx -y @zereight/mcp-gitlab@latest).
Auth: GITLAB_PERSONAL_ACCESS_TOKEN plus GITLAB_API_URL=https://gitlab.com/api/v4 (or GITLAB_USE_OAUTH=true).
Local: 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
Or: codex mcp add gitlab --env GITLAB_PERSONAL_ACCESS_TOKEN="$GITLAB_PERSONAL_ACCESS_TOKEN" --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab
Cursor: use the README deeplink or docs/clients/cursor.md.
Remote HTTP: point the client at https://mcp.example.com/mcp (Streamable HTTP). Claude.ai needs GITLAB_MCP_OAUTH on that host.
Default list: 40 tools (38 core + discover_tools + help). Call discover_tools to expand. Do not enable the api toolset unless you accept its bypass risk.
Equal non-MCP path: npx skills add zereight/gitlab-mcp --skill gitlab-mcp-skill plus the zereight-mcp-gitlab CLI.

远程 HTTP

这是托管或可自托管服务的首选方案。将客户端指向 Streamable HTTP URL：

{
  "mcpServers": {
    "gitlab": {
      "type": "http",
      "url": "https://mcp.example.com/mcp"
    }
  }
}

• 托管服务 / Claude.ai：在服务端设置 GITLAB_MCP_OAUTH=true（参见 MCP OAuth）
• 按用户提供 PAT 请求头：设置 REMOTE_AUTHORIZATION=true（参见远程授权）
• 本地 Docker 示例见使用方法

技能 + CLI（无需 MCP）

技能 + CLI 是平等的使用方式，并非备用方案。工作流相同，可在终端中获取完整负载，无需注册 MCP。

npx skills add zereight/gitlab-mcp --skill gitlab-mcp-skill
zereight-mcp-gitlab user whoami
zereight-mcp-gitlab mr list

请参阅 无需 MCP 的 CLI 和 skills/gitlab-mcp/。

MCP 与人工 CLI

使用 MCP 的情况	使用 CLI 的情况
Agent 需要在聊天中使用结构化工具	需要完整负载（差异、日志、构件）
jmespath 或精简结果已足够	已启用 GITLAB_MCP_COMPACT_RESULTS，且希望在终端中查看其余内容
已注册服务	有 PAT，或已运行 auth，且不想使用 MCP

人工 CLI 的结果永远不会被精简。破坏性工具和 GITLAB_TOOL_POLICY_APPROVE 工具需要使用 --yes。

提示

project_id 是数字 ID 或经过 URL 编码的路径。例如：group group、project project、merge request !123 → project_id=group%2Fproject、merge_request_iid=123。嵌套组的每个层级之间都要使用 %2F（group%2Fsubgroup%2Fproject）。

常见问题

如何进行身份验证？ 本地桌面环境中，GITLAB_PERSONAL_ACCESS_TOKEN（或 GITLAB_PERSONAL_ACCESS_TOKEN_FILE）是最简单的方式。本地 OAuth 使用 GITLAB_USE_OAUTH=true。远程 Claude.ai 使用 GITLAB_MCP_OAUTH。多用户 HTTP 使用 REMOTE_AUTHORIZATION 和每个请求附带的令牌标头。

为什么我只能看到大约 40 个工具？ 默认的 core 工具集包含 38 个工具，另有始终启用的 discover_tools 和 help。不带参数调用 discover_tools 可列出类别，然后传入某个类别（pipelines、wiki 等）即可在本次会话中启用它。GITLAB_TOOLSETS=all 仍然不会启用 api。

本地 OAuth、MCP OAuth 和远程身份验证有什么区别？ 本地 OAuth 会在与服务相同的机器上打开浏览器。MCP OAuth 面向公共 HTTPS 服务，以及 Claude.ai 等客户端。远程授权会转发调用方的 PAT 或作业令牌；无需进行 OAuth 授权流程。

如何缩小超大的回复？ 在任意工具调用中传入 jmespath。或者设置 GITLAB_MCP_COMPACT_RESULTS=true，让过大的 MCP 回复变为预览内容加一条 CLI 命令。需要完整负载时请使用 CLI。

为什么 api 工具集有风险？ gitlab_api_request 会绕过组／项目允许列表、其他工具筛选器和每个工具的安全检查。提示词注入可能驱动它。只有将 api 列入 GITLAB_TOOLSETS 时才启用它。all、discover_tools 和 GITLAB_TOOLS 都不会启用它。

Cursor 规则 / CLAUDE.md 片段

GitLab merge requests, issues, and pipelines go through this MCP (@zereight/mcp-gitlab).
Start with the default core tools. Call discover_tools to expand.
Prefer list_merge_request_changed_files, then batched get_merge_request_file_diff.
Use jmespath or compact results; use the CLI for full diffs and job logs.

@zereight/mcp-gitlab

针对 Agent 工作流优化的 GitLab MCP——通过 stdio、SSE 和 Streamable HTTP 管理项目、合并请求、议题、流水线、wiki、发布、标签、里程碑等。

支持 PAT、OAuth、只读模式、动态 API URL，以及面向 VS Code、Claude、Cursor、Copilot 和其他 MCP 客户端的远程授权。

为什么选择这个 GitLab MCP？

• 默认提供 40 个工具（38 个 core 工具 + discover_tools + help）；共 278 个工具 — 从精简配置开始；调用 discover_tools 即可激活更多工具，无需采用 CQRS 式分组
• MR 两步审查 — list_merge_request_changed_files → 批量调用 get_merge_request_file_diff
• 内置 Agent Skill — 在 skills/gitlab-mcp/ 中提供工作流指导
• 灵活的身份验证 — Personal Access Token、本地 OAuth2 浏览器流程、MCP OAuth 代理，以及按请求进行远程授权
• 支持多种传输方式 — 面向本地客户端的 stdio、面向旧版客户端的 SSE，以及面向现代远程部署的 Streamable HTTP
• 便于客户端配置 — 提供 Claude Code、Codex、Antigravity、OpenCode、Copilot、Cline、Roo Code、Cursor、Kilo Code 和 Amp Code 的示例
• 可用于自托管环境 — 支持自定义 GitLab 实例、代理设置和动态 API URL 路由
• JMESPath 结果筛选 — 在工具调用中可选使用 jmespath（参见 tools/list），无需更改 GitLab API 请求即可缩减 JSON 结果；启用响应遮蔽后，JMESPath 会对已遮蔽的数据运行。

对比一览

	@zereight/mcp-gitlab	GitLab MCP A（社区版 CQRS 式）	GitLab 官方 MCP 服务
适用场景	AI Agent 工作流	企业级多实例／分组工具	内置于 GitLab，无需单独安装
工具模型	278 个工具：工具集中的 275 个工具 + execute_graphql + discover_tools + help	约 50–60 个分组的 browse_*／manage_* 工具	通过 HTTP 请求头选择工具集
MR 审查	两步批量差异查看	不一而同	使用 get_merge_request 获取差异
Node.js	>=20.0.0	通常要求 >=24	通过 mcp-remote 使用 stdio 时需要 Node.js 20+
许可证	MIT	不一而同	GitLab 的组成部分

tools/list 大小（测量于 2026-10-24）

客户端会在会话开始时将整个 tools/list 结果发送给模型。Token 估算值为 UTF-8 字节数 / 4。

配置	工具数	JSON 字节数	估算 Token 数
默认（core + discover_tools + help）	40	50,682	12,671
GITLAB_TOOL_PROFILE=slim	39	49,646	12,412
GITLAB_TOOLSETS=all	276	285,677	71,420

修改描述或架构后，使用 npm run test:mock（test/tools-list-budget.test.ts）重新测量。

GitLab 也提供官方 MCP 服务。

• Free、Premium 和 Ultimate。已在 GitLab 19.2 中从 Premium 移至 Free。在 GitLab 19.5 中正式可用。
• 在 GitLab.com 上，顶级群组的 Owner 可允许访问 MCP 服务。在 GitLab Self-Managed 和 GitLab Dedicated 上，由管理员控制实例设置。默认规则请参阅官方页面。
• 远程客户端通过 HTTP https://<gitlab.example.com>/api/v4/mcp 使用 OAuth 2.0 动态客户端注册。
• stdio 通过 mcp-remote 连接，并需要 Node.js 20 或更高版本。
• 工具集使用 X-Gitlab-Enabled-Mcp-Server-Toolsets 标头。可选的 X-Gitlab-Mcp-Server-Tool-Name-Prefix 标头会保留工具名称前缀的前 32 个字符。

与 GitLab 官方 MCP 服务的完整比较 →

快速开始：选择下方的个人访问令牌或 OAuth2 设置，安装 @zereight/mcp-gitlab，并在 MCP 客户端配置中使用 zereight-mcp-gitlab。

客户端设置指南

• Claude Code 设置指南
• VS Code 设置指南
• GitHub Copilot 设置指南
• Codex 设置指南
• Cursor 设置指南
• 基于 JSON 的 MCP 客户端设置指南 - 适用于 Factory AI Droid、OpenClaw 和 OpenCode 风格的客户端
• OAuth2 身份验证设置指南
• 环境变量参考
• 无状态模式 — 多 Pod HPA
• 自定义 Agent 和多个 PAT 设置

使用方法

设置概览

身份验证方式

服务支持四种身份验证方式：

用于本地/桌面使用（最常见）：

1. 个人访问令牌（GITLAB_PERSONAL_ACCESS_TOKEN 或 GITLAB_PERSONAL_ACCESS_TOKEN_FILE）——设置最简单
2. OAuth2 — 本地浏览器（GITLAB_USE_OAUTH）——推荐，安全性更高

用于服务端/远程部署：

3. OAuth2 — MCP 代理（GITLAB_MCP_OAUTH）——适用于 Claude.ai 等远程 MCP 客户端
4. 远程授权（REMOTE_AUTHORIZATION）——多用户部署时，每个调用方都提供自己的令牌

快速设置路径

• Claude Code：请参阅 Claude Code 设置指南
• VS Code：请参阅 VS Code 设置指南
• GitHub Copilot：请参阅 GitHub Copilot 设置指南
• Codex：请参阅 Codex 设置指南
• Cursor：请参阅 Cursor 设置指南
• Factory AI Droid / OpenClaw / OpenCode 风格的客户端：请参阅 基于 JSON 的 MCP 客户端设置指南
• OAuth 浏览器流程详情：请参阅 OAuth2 身份验证设置指南
• 不使用 localhost 回调的 OAuth（SSO、远程 Shell、后台客户端）：运行 zereight-mcp-gitlab auth（GitLab 17.9+ 使用设备流程；17.2–17.8 需要 oauth2_device_grant_flow），然后使用 GITLAB_USE_OAUTH=true 启动服务。请参阅独立设备流程命令。

最简单的本地设置方式是从个人访问令牌开始。本地浏览器身份验证请使用 OAuth2。对于远程或多用户部署，请继续阅读本 README 后续的 MCP OAuth 和远程授权部分。

安装一次服务：

brew tap zereight/gitlab-mcp https://github.com/zereight/gitlab-mcp
brew install zereight/gitlab-mcp/zereight-mcp-gitlab

或使用 npm：

npm install -g @zereight/mcp-gitlab

或使用 Nix，将此 flake 添加到你自己的配置中：

# flake.nix
inputs.gitlab-mcp.url = "github:zereight/gitlab-mcp";

# wherever you configure your MCP client:
command = lib.getExe inputs.gitlab-mcp.packages.${system}.default;

存储路径由锁定文件固定；使用 nix flake update gitlab-mcp 更新。

示例使用 zereight-mcp-gitlab，这是一个不易冲突的别名，指向旧版 mcp-gitlab 二进制文件。如果你的 MCP 客户端找不到它，请使用 which zereight-mcp-gitlab 返回的绝对路径。

不想全局安装？将 npx 固定到上一个稳定版本（本文档推荐的版本），例如 npx -y @zereight/[email protected]。如果始终想使用最新版本，请改用 npx -y @zereight/mcp-gitlab@latest。若要在下一个稳定版本发布前试用已合并到 main 的修复，请使用 npx -y @zereight/mcp-gitlab@next。这是预发布构建，不适用于生产环境。服务启动时，如果有更新版本可用，会向 stderr 输出提示（使用 GITLAB_DISABLE_VERSION_CHECK=true 可禁用）。

Claude Desktop 一键安装（MCP Bundle）

v2.3.1 之后的每个 GitHub 版本都会附带一个 gitlab-mcp.mcpb MCP Bundle。下载最新 Bundle，并使用 Claude Desktop 打开（或将其拖入 Settings → Extensions）。Claude Desktop 会要求你提供个人访问令牌（以敏感值存储），并允许你设置 GITLAB_API_URL、GITLAB_PERMISSION_MODE、GITLAB_TOOLSETS 和 GITLAB_MASKING_ENABLED。无需单独安装 Node.js 或 npm。

要从源代码构建 Bundle，请运行 npm run pack:mcpb（生成 gitlab-mcp.mcpb）。

使用 CLI 参数（适用于环境变量有问题的客户端）

某些 MCP 客户端（如 GitHub Copilot CLI）在使用环境变量时会遇到问题。请改用 CLI 参数：

{
  "mcpServers": {
    "gitlab": {
      "command": "zereight-mcp-gitlab",
      "args": ["--token=YOUR_GITLAB_TOKEN", "--api-url=https://gitlab.com/api/v4"],
      "tools": ["*"]
    }
  }
}

可用的 CLI 参数：

• --token - GitLab 个人访问令牌（替代 GITLAB_PERSONAL_ACCESS_TOKEN）
• --api-url - GitLab API URL（替代 GITLAB_API_URL）
• --read-only=true - 已弃用（将在下一个主版本（v3.0.0）中移除）；请改用 --permission-mode=readonly（替代 GITLAB_READ_ONLY_MODE）
• --permission-mode - 权限级别：readonly、modify（不含删除或拆除工具），或 full（替代 GITLAB_PERMISSION_MODE，默认值为 full）
• --toolsets=all - 启用命名工具集，但不包括仅显式启用的 api 工具集（替代 GITLAB_TOOLSETS；未设置时使用精简的 core 默认值）。gitlab_api_request 需要 --toolsets=api
• --tools=list_issues - 添加单个工具（替代 GITLAB_TOOLS）
• --use-wiki=true - 已弃用（将在下一个主版本（v3.0.0）中移除）；请改用 --toolsets=core,wiki（替代 USE_GITLAB_WIKI）
• --use-milestone=true - 已弃用（将在下一个主版本（v3.0.0）中移除）；请改用 --toolsets=core,milestones（替代 USE_MILESTONE）
• --use-pipeline=true - 已弃用（将在下一个主版本（v3.0.0）中移除）；请改用 --toolsets=core,pipelines，并将 validate_ci_lint,validate_project_ci_lint 追加到现有的 --tools 列表中（如果该列表未设置，则设置 --tools=validate_ci_lint,validate_project_ci_lint）（替代 USE_PIPELINE）
• --disable-version-check=true - 禁用启动时的新版本提示（替代 GITLAB_DISABLE_VERSION_CHECK）
• --masking-enabled=true - 启用文本响应遮蔽（替代 GITLAB_MASKING_ENABLED）
• --masking-config - 遮蔽配置文件的路径（替代 GITLAB_MASKING_CONFIG）
• --masking-policy-file - 受保护的托管策略文件的路径（替代 GITLAB_MASKING_POLICY_FILE）
• --masking-workspace-dir - 用于解析遮蔽文件的目录（替代 GITLAB_MASKING_WORKSPACE_DIR）
• --download-dir - download_attachment 和 download_job_artifacts 保存文件的目录（替代 GITLAB_DOWNLOAD_DIR；默认值为 .gitlab-mcp-downloads）
• --compact-results=true - 截断过大的 MCP 工具回复，并附上用于获取完整负载的 CLI 命令（替代 GITLAB_MCP_COMPACT_RESULTS；默认关闭）
• --compact-result-chars - 启用紧凑处理的字符数阈值（替代 GITLAB_MCP_COMPACT_RESULT_CHARS；默认值为 4000）
• --compact-tools - 以逗号分隔的工具名称列表；仅在回复过大时对这些工具进行紧凑处理，不会开启全局紧凑处理（替代 GITLAB_MCP_COMPACT_TOOLS）
• --list-summary-default=true - list_* 工具和 mr_discussions 会将省略的 summary 参数视为 true；summary: false 仍会返回完整 JSON（替代 GITLAB_MCP_LIST_SUMMARY_DEFAULT；默认关闭）
• --tool-profile - full（默认值）或 slim。slim 会从初始列表中移除草稿注释、表情回应、标签、CI 目录工具和 create_group。设置了 GITLAB_TOOLSETS 时，此选项会被忽略（替代 GITLAB_TOOL_PROFILE）

如果已设置 GITLAB_TOOLSETS 或 --toolsets，请将 wiki、milestones 或 pipelines 追加到该列表中，而不是替换它。如果已设置 GITLAB_TOOLS 或 --tools，请将 validate_ci_lint 和 validate_project_ci_lint 追加到该列表中，而不是替换它。显式列表会替代默认的 core 工具集，而不会与之合并。

CLI 参数优先于环境变量。

zereight-mcp-gitlab auth 是一个子命令（不是 MCP 服务标志）。它会运行 GitLab 设备授权流程，然后退出。请参阅CLI 参数。 同一个二进制文件也可用作类似 gh 的 GitLab CLI（tool <name> 或 mr list 等精选形式）。无需注册 MCP——设置 PAT，或运行 auth 并设置 GITLAB_USE_OAUTH=true：请参阅 无需 MCP 使用 CLI。setup --cursor / setup --claude 会输出客户端配置；doctor 会检查令牌、API URL、工具集和版本。在终端中使用它可获取完整负载。MCP 回复会保留在聊天中，除非设置 GITLAB_MCP_COMPACT_RESULTS=true（或使用 --compact-results），此时超大的工具回复会替换为预览和 CLI 命令。人类 CLI 的回复永远不会被精简。权限模式、工具集、拒绝工具正则表达式和工具策略过滤器均相同。破坏性工具和 GITLAB_TOOL_POLICY_APPROVE 工具需要使用 --yes。请参阅人类 CLI。

**精细的工具过滤：**使用 GITLAB_PERMISSION_MODE=modify，允许创建/更新，同时 阻止所有删除工具和破坏性拆除工具（cancel_pipeline、 cancel_pipeline_job、stop_environment、stop_stale_environments、unprotect_branch、 unprotect_tag）—— 也包括通过 execute_graphql 和 push_files 的 delete/move 操作执行的破坏性变更（删除和拆除动词）——或者使用 GITLAB_PERMISSION_MODE=readonly 进行只读 访问。你也可以 使用 GITLAB_TOOLSETS=<group,…> 启用工具集组，使用 GITLAB_TOOLS=<tool,…> 将单个工具加入允许列表（例如，只读组加上少数特定写入工具），并使用 GITLAB_DENIED_TOOLS_REGEX 按模式加入拒绝列表。旧版 USE_GITLAB_WIKI / USE_MILESTONE / USE_PIPELINE 标志已弃用（将在下一个主要版本 v3.0.0 中移除）。 请改用 GITLAB_TOOLSETS=core,wiki、core,milestones 或 core,pipelines （USE_PIPELINE 还需要将 validate_ci_lint,validate_project_ci_lint 追加到现有的 GITLAB_TOOLS 列表，而不是替换该列表）。 如果你已设置 GITLAB_TOOLSETS，请将工具集追加到现有列表，而不是替换列表。 如果未设置 GITLAB_TOOLS，请设置 GITLAB_TOOLS=validate_ci_lint,validate_project_ci_lint。如果已设置，请追加 validate_ci_lint,validate_project_ci_lint，而不是替换该列表。 请参阅工具参考和 环境变量。

注意

gitlab_api_request（工具集 api）会绕过 GITLAB_ALLOWED_GROUPS 和其他组限制、项目允许列表、工具级限制（其他工具上的 GITLAB_TOOLS、GITLAB_DENIED_TOOLS_REGEX）以及单个工具的安全检查。完整的令牌权限范围都会暴露。提示词注入可能会驱动此工具。依赖这些限制的运维人员切勿启用此工具。 只有将 api 列入 GITLAB_TOOLSETS 时才能启用此工具（GITLAB_TOOLSETS=all、discover_tools、GITLAB_TOOLS、旧版 USE_* 标志和 GITLAB_TOOL_PROFILE 均不能启用它）。设置了 GITLAB_ALLOWED_PROJECT_IDS 或会话项目范围时，只接受针对允许项目的 /projects/:id 路径。诸如 /search、/users、/groups/:id 和 /runners 等端点会被拒绝。不会检查指定其他项目的请求体和查询参数。不会强制执行 GITLAB_PROJECT_ID 和 OAuth 组允许列表。

• sse

只传入变量名。Docker 客户端会将已导出的 GITLAB_PERSONAL_ACCESS_TOKEN 复制到容器中。

docker run -i --rm \
  -e HOST=0.0.0.0 \
  -e GITLAB_PERSONAL_ACCESS_TOKEN \
  -e GITLAB_API_URL="https://gitlab.com/api/v4" \
  -e GITLAB_PERMISSION_MODE=readonly \
  -e GITLAB_TOOLSETS=core,wiki,milestones,pipelines \
  -e SSE=true \
  -e SSE_AUTH_TOKEN=your_mcp_sse_token \
  -p 3333:3002 \
  zereight050/gitlab-mcp

{
  "mcpServers": {
    "gitlab": {
      "type": "sse",
      "url": "http://localhost:3333/sse",
      "headers": {
        "Authorization": "Bearer your_mcp_sse_token"
      }
    }
  }
}

• streamable-http

docker run -i --rm \
  -e HOST=0.0.0.0 \
  -e REMOTE_AUTHORIZATION=true \
  -e GITLAB_API_URL="https://gitlab.com/api/v4" \
  -e GITLAB_PERMISSION_MODE=readonly \
  -e GITLAB_TOOLSETS=core,wiki,milestones,pipelines \
  -e STREAMABLE_HTTP=true \
  -p 3333:3002 \
  zereight050/gitlab-mcp

{
  "mcpServers": {
    "gitlab": {
      "type": "streamable-http",
      "url": "http://localhost:3333/mcp",
      "headers": {
        "Authorization": "Bearer glpat-..."
      }
    }
  }
}

使用 MCP OAuth 代理（GITLAB_MCP_OAUTH）

**仅用于服务端/远程部署。**此模式要求将 MCP 服务部署到可公开访问的 HTTPS URL。对于本地/桌面使用，请参阅上文的 GITLAB_USE_OAUTH。

适用于支持 MCP OAuth 规范的远程 MCP 客户端（例如 Claude.ai）。 服务端充当完整的 OAuth 2.0 授权服务器——未经身份验证的请求 会收到 401 + WWW-Authenticate 响应，从而自动触发客户端侧的 OAuth 浏览器流程。 OpenCode、MCPJam 和 Claude.ai 等远程 MCP 客户端可以在授权时发送各自的回调 URL。如果无法在 GitLab 中注册每个客户端的回调 URL，请启用 GITLAB_OAUTH_CALLBACK_PROXY=true。在回调代理模式下，GitLab 只需注册一个重定向 URI：{MCP_SERVER_URL}/callback。

GITLAB_OAUTH_REDIRECT_URI 仅用于本地 OAuth（GITLAB_USE_OAUTH）。它不会覆盖远程 MCP OAuth 客户端的回调 URL，也不应用于修复远程 Unregistered redirect_uri 错误。

之所以有此变量，是因为本地 OAuth 流会在与 MCP 服务相同的机器上启动浏览器，并在本地 HTTP 服务上监听回调，例如 http://127.0.0.1:8888/callback。

远程 MCP OAuth 则不同。在 GITLAB_MCP_OAUTH=true 模式下，MCP 客户端会在 /authorize 期间提供自己的回调 URL。GITLAB_OAUTH_REDIRECT_URI 不会替换客户端提供的 URL。

模式	启用方式	回调变量	GitLab 重定向 URI
本地 OAuth	GITLAB_USE_OAUTH=true	GITLAB_OAUTH_REDIRECT_URI	http://127.0.0.1:8888/callback 或你的本地回调
远程 MCP OAuth	GITLAB_MCP_OAUTH=true	GITLAB_OAUTH_CALLBACK_PROXY=true	{MCP_SERVER_URL}/callback

仅当 MCP 服务本身管理本地浏览器回调时，才使用 GITLAB_OAUTH_REDIRECT_URI。当远程 MCP 客户端管理回调 URL 时，使用 GITLAB_OAUTH_CALLBACK_PROXY=true。

工作原理：将此 MCP 服务部署到具有公开 HTTPS URL 的位置。MCP 客户端连接到 {MCP_SERVER_URL}/mcp。服务负责处理 OAuth 2.0 流程，代表客户端与 GitLab 交换凭据。

先决条件：

1. 可公开访问的 HTTPS 服务 URL（MCP_SERVER_URL）——本地测试时可使用 ngrok
2. 预先注册的 GitLab OAuth 应用，并具有 api（或 read_api）作用域 — 前往 Admin area → Applications，将重定向 URI 设为 {MCP_SERVER_URL}/callback | 环境变量 | 必需 | 描述 | | ----------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- | | GITLAB_MCP_OAUTH | ✅ | 设置为 true 以启用 | | GITLAB_API_URL | ✅ | GitLab API 基础 URL。请勿在 URL 中嵌入凭据（user:pass@）；这些凭据会被忽略。密码中的逗号必须写为 %2C。 | | GITLAB_OAUTH_APP_ID | ✅ | GitLab OAuth 应用程序 ID | | MCP_SERVER_URL | ✅ | 此 MCP 服务的公开 HTTPS URL | | STREAMABLE_HTTP | ✅ | 必须为 true | | GITLAB_OAUTH_CALLBACK_PROXY | 可选 | 设置为 true 以使用 MCP 服务固定的 /callback URL | | GITLAB_OAUTH_ALLOWED_REDIRECT_URIS | 可选 | 回调代理模式将重定向到的客户端回调 URL（默认值：Claude、ChatGPT、Cursor 和 loopback 回调；使用 defaults,<url> 添加一个） | | GITLAB_OAUTH_SCOPES | 可选 | 以逗号分隔的作用域（默认值：api,read_api,read_user） | | GITLAB_OAUTH_ALLOWED_GROUPS | 可选 | 以逗号分隔的群组完整路径 — 只有成员（及子群组成员）可以使用此服务（替代已弃用的 GITLAB_ALLOWED_GROUPS） | | OAUTH_DISABLE_REFRESH_TOKEN | 可选 | 设置为 true，不签发刷新令牌：每次 GitLab 访问令牌过期（2 h）时，用户都必须在浏览器中重新授权，无论会话 TTL 如何 |

当 STREAMABLE_HTTP=true 时，服务端 GitLab 凭据（GITLAB_PERSONAL_ACCESS_TOKEN、GITLAB_JOB_TOKEN、GITLAB_AUTH_COOKIE_PATH 或 GITLAB_USE_OAUTH）需要 REMOTE_AUTHORIZATION=true、GITLAB_MCP_OAUTH=true 或 STREAMABLE_HTTP_AUTH_TOKEN。

排查 Unregistered redirect_uri

检查浏览器 URL 中的 redirect_uri。如果它指向客户端回调， 例如 http://127.0.0.1:xxxxx/.../callback，请启用：

GITLAB_OAUTH_CALLBACK_PROXY=true

请勿通过更改 GITLAB_OAUTH_REDIRECT_URI 来修复远程 MCP OAuth。 此变量仅用于本地 OAuth（GITLAB_USE_OAUTH）。

docker run -i --rm \
  -e HOST=0.0.0.0 \
  -e GITLAB_MCP_OAUTH=true \
  -e GITLAB_OAUTH_CALLBACK_PROXY=true \
  -e STREAMABLE_HTTP=true \
  -e MCP_SERVER_URL=https://your-server.example.com \
  -e GITLAB_API_URL="https://gitlab.com/api/v4" \
  -e GITLAB_OAUTH_APP_ID=your_app_id \
  -p 3000:3002 \
  zereight050/gitlab-mcp

MCP 客户端配置：

{
  "mcpServers": {
    "gitlab": {
      "type": "http",
      "url": "https://your-server.example.com/mcp"
    }
  }
}

使用远程授权（REMOTE_AUTHORIZATION）

仅适用于服务端／远程部署。 每个 HTTP 调用方都在请求标头中直接提供自己的 GitLab 令牌，不涉及 OAuth 流程。

适用于多用户或多租户部署，此类部署中的每个调用方都会在 HTTP 请求标头中提供自己的 GitLab 令牌。无需 OAuth 流程——MCP 服务会代表调用方将令牌转发给 GitLab。

标头优先级：Private-Token > JOB-TOKEN > Authorization: Bearer

环境变量	必需	描述
REMOTE_AUTHORIZATION	✅	设置为 true 以启用
STREAMABLE_HTTP	✅	必须为 true
ENABLE_DYNAMIC_API_URL	可选	允许通过 X-GitLab-API-URL 标头为每个请求指定 GitLab URL
GITLAB_ALLOWED_HOSTS	可选	以逗号分隔的允许使用 X-GitLab-API-URL 的主机；始终允许使用 GITLAB_API_URL 的主机。也会将这些主机视为可信下载重定向目标（发布资源、作业制品、上传的附件）；请在此处列出专用网络主机
GITLAB_ALLOW_UNAUTHENTICATED_TOOL_DISCOVERY	可选	仅允许未经身份验证的 initialize、notifications/initialized、tools/list 和 server/discover（调用工具仍需身份验证）
MCP_SERVER_URL / MCP_ALLOWED_HOSTS / MCP_ALLOWED_ORIGINS	可选	用于 DNS 重绑定防护的允许公开 /mcp 主机／来源值
MCP_TRUST_PROXY	可选	在反向代理后信任 Forwarded / X-Forwarded-* 标头（下载 URL、Express req.ip、/mcp IP 速率限制、OAuth 速率限制）

GITLAB_ALLOW_UNAUTHENTICATED_TOOL_DISCOVERY=true 适用于需要在用户提供 GitLab 令牌前检查工具元数据的 MCP 网关或管理员界面。除非部署中公开工具列表是安全的，否则请保持禁用。

未设置 MCP_SERVER_URL 时，远程下载 URL 会回退到本地 服务地址。仅当服务器可通过可信反向代理访问，且 MCP 服务不允许客户端直接访问时，才设置 MCP_TRUST_PROXY=true。 这会为 Streamable HTTP 和 SSE 启用 Express trust proxy，根据 Forwarded / X-Forwarded-Proto / X-Forwarded-Host / X-Forwarded-Prefix 生成公开下载 URL，并在代理发送的 X-Forwarded-For 中包含客户端端口（例如 1.2.3.4:5678）时，确保 OAuth 端点速率限制正常工作。 引入此标志后，现有的 OAuth + 代理部署必须显式设置该标志。

请求标头示例：

Private-Token: glpat-xxxxxxxxxxxxxxxxxxxx

或使用 Bearer 令牌：

Authorization: Bearer glpat-xxxxxxxxxxxxxxxxxxxx

⚠️ REMOTE_AUTHORIZATION 不兼容 SSE 传输。必须设置 STREAMABLE_HTTP=true。

环境变量

如需查看完整的环境变量列表，请参阅专门的参考文档：

• 环境变量参考

大多数用户只需从以下配置组合中选择一种：

• 本地 PAT：GITLAB_PERSONAL_ACCESS_TOKEN、GITLAB_API_URL
• 本地 OAuth：GITLAB_USE_OAUTH=true、GITLAB_OAUTH_CLIENT_ID、GITLAB_OAUTH_REDIRECT_URI、GITLAB_API_URL
• 远程多用户 HTTP：STREAMABLE_HTTP=true、REMOTE_AUTHORIZATION=true（或 GITLAB_MCP_OAUTH=true）、MCP_TRUST_PROXY=true（位于反向代理后时）、MAX_REQUESTS_PER_MINUTE=300、MCP_SERVER_URL 或 MCP_ALLOWED_HOSTS、HOST、PORT
• 多个并行部署：为每个实例设置不同的 MCP_SERVER_NAME（例如 gitlab-selfhosted-readonly），以便客户端、日志和遥测数据能够区分它们
• 多 Pod HPA（无状态）：在上述配置基础上添加 OAUTH_STATELESS_MODE=true 和 OAUTH_STATELESS_SECRET（所有 Pod 的值必须相同）。请参阅无状态模式。

常用变量：

• GITLAB_API_URL
• GITLAB_PERSONAL_ACCESS_TOKEN
• GITLAB_USE_OAUTH
• REMOTE_AUTHORIZATION
• MCP_TRUST_PROXY
• MAX_REQUESTS_PER_MINUTE
• MAX_SESSIONS
• MCP_ALLOWED_HOSTS
• MCP_ALLOWED_ORIGINS
• GITLAB_MCP_OAUTH
• GITLAB_OAUTH_CALLBACK_PROXY
• GITLAB_OAUTH_ALLOWED_REDIRECT_URIS
• OAUTH_REGISTER_RATE_LIMIT_PER_HOUR
• OAUTH_DISABLE_REFRESH_TOKEN
• OAUTH_STATELESS_MODE
• OAUTH_STATELESS_SECRET

参考文档还介绍了：

• 身份验证和 OAuth 变量
• MCP OAuth 代理变量
• 项目和工具筛选变量
• 通过 discover_tools 动态发现工具（按需启用工具集）
• 传输和会话变量
• 代理和 TLS 变量

有关回调代理模式的详细信息，请参阅 GitLab MCP OAuth 回调代理。

SSE 会话限制

GET /sse 受与 Streamable HTTP 相同的远程传输控制约束：

• **容量：**并发 SSE 会话数最多为 MAX_SESSIONS（默认值为 1000）；超出后，新连接会收到 503。
• **创建速率限制：**每个客户端 IP 的新连接速率限制为 MAX_REQUESTS_PER_MINUTE（默认值为 60）；超出后，新连接会收到 429。
• 空闲超时：如果会话在 SESSION_TIMEOUT_SECONDS（默认值为 1 小时）内未收到 POST /messages 请求，则会关闭该会话。因此，空闲客户端必须重新连接，而不能继续占用容量名额。与 Streamable HTTP 不同，保持 SSE 流打开不算活动。
• 实例达到容量上限时，/health 会返回 503，且状态为 status: "degraded"。

可通过 MAX_SESSIONS、MAX_REQUESTS_PER_MINUTE 和 SESSION_TIMEOUT_SECONDS 调整这些设置。

远程授权设置（多用户支持）

使用 REMOTE_AUTHORIZATION=true 时，MCP 服务可以支持多个用户，每位用户都可通过 HTTP 标头传入自己的 GitLab 令牌。这适用于：

• 每位用户都需要使用自己的 GitLab 访问权限的共享 MCP 服务实例
• 能够将用户专属令牌注入 MCP 请求的 IDE 集成

设置示例：

# Start server with remote authorization
docker run -d \
  -e HOST=0.0.0.0 \
  -e STREAMABLE_HTTP=true \
  -e REMOTE_AUTHORIZATION=true \
  -e GITLAB_API_URL="https://gitlab.com/api/v4" \
  -e GITLAB_PERMISSION_MODE=readonly \
  -e SESSION_TIMEOUT_SECONDS=3600 \
  -p 3333:3002 \
  zereight050/gitlab-mcp

客户端配置：

你的 IDE 或 MCP 客户端必须在每个请求中发送以下标头之一：

Authorization: Bearer glpat-xxxxxxxxxxxxxxxxxxxx

或

Private-Token: glpat-xxxxxxxxxxxxxxxxxxxx

令牌会按会话存储（会话由 mcp-session-id 标头标识），并用于同一会话中的后续请求。会话归属于该令牌对应的 GitLab 用户：使用其他用户的令牌发起请求会收到 404 Session not found；不带令牌的 GET / DELETE /mcp 请求会收到 401。

使用 Cursor 的远程授权客户端配置示例

{
  "mcpServers": {
    "GitLab": {
      "url": "http(s)://<your_mcp_gitlab_server>/mcp",
      "headers": {
        "Authorization": "Bearer glpat-..."
      }
    }
  }
}

重要说明：

• 远程授权仅适用于 Streamable HTTP 传输
• 每个会话彼此隔离，一个会话的令牌无法访问另一个会话的数据。 会话关闭时，令牌会自动清理。
• **会话超时：**身份验证令牌在 SESSION_TIMEOUT_SECONDS 指定的无活动时长后过期（默认 1 小时）。超时后，客户端必须重新发送身份验证标头。传输会话仍保持活动状态。
• 每个请求都会重置该会话的超时计时器。
• 速率限制：/mcp 请求受客户端 IP 的 MAX_REQUESTS_PER_MINUTE 限制；使用 OAuth 或远程授权时，还受每个 MCP 会话的该限制约束（默认 60）。请参阅 environment-variables.md。
• **容量限制：**服务最多接受 MAX_SESSIONS 个并发会话（默认 1000）

MCP OAuth 设置（Claude.ai 原生 OAuth）

使用 GITLAB_MCP_OAUTH=true 时，服务会充当连接到你的 GitLab 实例的 OAuth 代理。Claude.ai（以及任何符合 MCP 规范的客户端）会自动处理整个浏览器身份验证流程，无需手动管理个人访问令牌。

前提条件：

必须有一个预先注册的 GitLab OAuth 应用。GitLab 将动态注册的（未经验证的）应用限制为 mcp 范围，这不足以调用 API（需要 api 或 read_api）。

1. 前往你的 GitLab 实例 → 管理区域 > 应用程序（实例范围）或 用户设置 > 应用程序（个人）
2. 创建一个新应用，并设置：
   • 机密：取消勾选
   • 范围：api、read_api、read_user（或你打算通过 GITLAB_OAUTH_SCOPES 请求的范围）
3. 保存并复制应用程序 ID——这就是你的 GITLAB_OAUTH_APP_ID

工作原理：

1. 用户在 Claude.ai 中添加你的 MCP 服务 URL
2. Claude.ai 通过 /.well-known/oauth-authorization-server 发现 OAuth 端点
3. Claude.ai 通过动态客户端注册（POST /register）注册自身——由 MCP 服务在本地处理（每个客户端都会获得一个虚拟客户端 ID）
4. Claude.ai 使用预先注册的 OAuth 应用，将用户的浏览器重定向到 GitLab 登录页面
5. 用户完成身份验证；GitLab 将用户重定向回 https://claude.ai/api/mcp/auth_callback
6. Claude.ai 在每个 MCP 请求中发送 Authorization: Bearer <token>
7. 服务向 GitLab 验证令牌，并按会话存储令牌

服务设置：

docker run -d \
  -e STREAMABLE_HTTP=true \
  -e GITLAB_MCP_OAUTH=true \
  -e GITLAB_OAUTH_APP_ID="your-gitlab-oauth-app-client-id" \
  -e GITLAB_API_URL="https://gitlab.example.com/api/v4" \
  -e MCP_SERVER_URL="https://your-mcp-server.example.com" \
  -p 3002:3002 \
  zereight050/gitlab-mcp

本地开发时（允许使用 HTTP）：

MCP_DANGEROUSLY_ALLOW_INSECURE_ISSUER_URL=true \
STREAMABLE_HTTP=true \
GITLAB_MCP_OAUTH=true \
GITLAB_OAUTH_APP_ID=your-gitlab-oauth-app-client-id \
MCP_SERVER_URL=http://localhost:3002 \
GITLAB_API_URL=https://gitlab.com/api/v4 \
node build/index.js

Claude.ai 配置：

{
  "mcpServers": {
    "GitLab": {
      "url": "https://your-mcp-server.example.com/mcp"
    }
  }
}

无需 headers 字段——Claude.ai 会通过 OAuth 自动获取令牌。

环境变量：

变量	必填	描述
GITLAB_MCP_OAUTH	是	设置为 true 以启用
GITLAB_OAUTH_APP_ID	是	预先注册的 GitLab OAuth 应用的客户端 ID
MCP_SERVER_URL	是	MCP 服务的公共 HTTPS URL；也允许用于 /mcp Host/Origin 检查
GITLAB_API_URL	是	你的 GitLab 实例 API URL（例如 https://gitlab.com/api/v4）。请勿在 URL 中嵌入凭据（user:pass@）；这些凭据会被忽略。密码中的逗号必须写作 %2C。
STREAMABLE_HTTP	是	必须为 true（不支持 SSE）
GITLAB_OAUTH_SCOPES	否	以逗号分隔的 GitLab 权限范围（例如 api,read_user）。默认为 api（或在有效权限模式为 readonly 时默认为 read_api）。预先注册的应用必须配置至少这些权限范围。
OAUTH_REGISTER_RATE_LIMIT_PER_HOUR	否	动态客户端注册（POST /register）的每 IP 滚动限制。默认为每小时 20 次；范围为 1–1000。如果客户端（例如多个 IDE 窗口）触发注册限流，请调高此值。这不是 GitLab API 限制。
OAUTH_DISABLE_REFRESH_TOKEN	否	设置为 true，即可从 /token 响应中移除 refresh_token，并以 invalid_grant 拒绝刷新授权，使用户在 GitLab 访问令牌过期时通过浏览器重新授权。默认为 false。在回调代理模式下，遵循此服务流程的 MCP 客户端永远不会收到 GitLab 刷新令牌（在直通模式下，客户端可以直接从 GitLab 获取刷新令牌）。这是面向标准 MCP 客户端的重新授权策略，不是安全边界。启用此选项前签发的刷新令牌仍然有效，直到在 GitLab 的 用户设置 → 应用程序 → 已授权的应用程序 → 撤销 中撤销为止。
MCP_DANGEROUSLY_ALLOW_INSECURE_ISSUER_URL	否	仅用于本地 HTTP 开发时设置为 true

重要说明：

• MCP OAuth 仅适用于 Streamable HTTP 传输（SSE=true 不兼容）
• 每个用户会话都存储自己的 OAuth 令牌——会话完全隔离
• 会话超时、速率限制和容量限制与 REMOTE_AUTHORIZATION 模式完全相同（SESSION_TIMEOUT_SECONDS、MAX_REQUESTS_PER_MINUTE、MAX_SESSIONS）
• DCR 速率限制：POST /register 按客户端 IP 限制为每小时 OAUTH_REGISTER_RATE_LIMIT_PER_HOUR 次（默认每小时 20 次）。此限制独立于 /mcp 限制和 GitLab API 配额。详见 environment-variables.md。
• **请求头认证回退：**如果请求中包含 Private-Token 或 JOB-TOKEN 请求头，则跳过 OAuth 验证，并在该会话中直接使用原始令牌。这使 PAT 和 CI 作业令牌可以与 OAuth 流程同时用于同一服务器实例。Authorization: Bearer 始终被视为 OAuth 令牌——使用 Private-Token 进行基于 PAT 的请求头认证。

Agent 技能文件

技能 + CLI 是与 MCP 并列的使用方式（参见 技能 + CLI）。对于支持加载技能／指令的 AI Agent（Claude Code、GitHub Copilot、Cursor 等），可使用 skills/gitlab-mcp/ 中预先构建的技能文件。

• SKILL.md — 核心指南（约 800 个令牌），包含工具集概览、关键工作流和参数提示
• reference/ — 代码审查、合并请求、议题、流水线和漏洞分流的详细工作流文档

使用 skills CLI 安装：

npx skills add zereight/gitlab-mcp --skill gitlab-mcp-skill

在 AI 客户端中注册技能目录，即可获得最佳工具使用指导，而无需仅依赖完整的 ListTools 响应。

工具 🛠️

点击展开

1. `merge_merge_request` - 合并合并请求 2. `approve_merge_request` - 批准合并请求 3. `unapprove_merge_request` - 撤销对合并请求的批准 4. `get_merge_request_approval_state` - 获取合并请求的批准详情，包括批准者 5. `get_merge_request_conflicts` - 获取合并请求中的冲突 6. `list_merge_request_pipelines` - 分页列出合并请求的流水线 7. `execute_graphql` - 执行 GitLab GraphQL 查询 8. `create_or_update_file` - 在 GitLab 项目中创建或更新文件 9. `search_repositories` - 搜索 GitLab 项目 10. `create_repository` - 创建新的 GitLab 项目 11. `create_group` - 创建新群组或子群组 12. `get_file_contents` - 获取 GitLab 项目中文件或目录的内容 13. `push_files` - 在一次提交中推送多个文件 14. `create_issue` - 创建新议题 15. `create_merge_request` - 创建新的合并请求 16. `fork_repository` - 将项目复刻到你的账户或指定命名空间 17. `create_branch` - 创建新分支 18. `get_branch` - 获取分支详情（提交、保护状态） 19. `list_branches` - 列出项目中的分支，支持搜索筛选 20. `delete_branch` - 删除项目中的分支 21. `list_protected_branches` - 列出项目中的受保护分支，支持搜索筛选 22. `get_protected_branch` - 获取单个受保护分支的详情（访问级别、强制推送设置） 23. `protect_branch` - 保护仓库分支（设置推送、合并和取消保护的访问级别） 24. `update_protected_branch` - 原位更新现有的受保护分支规则（访问级别、强制推送、代码所有者批准） 25. `unprotect_branch` - 取消先前受保护分支的保护 26. `update_default_branch` - 更改项目的默认分支 27. `get_merge_request` - 获取合并请求详情（必须提供 merge_request_iid 或 source_branch）。设置 include_summaries=true 可获取部署、提交和批准摘要 28. `get_merge_request_diffs` - 获取合并请求的更改／差异（必须提供 merge_request_iid 或 source_branch） 29. `list_merge_request_changed_files` - 列出合并请求中已更改的文件路径，不包含差异内容（必须提供 merge_request_iid 或 source_branch） 30. `list_merge_request_diffs` - 分页列出合并请求差异（必须提供 merge_request_iid 或 source_branch） 31. `get_merge_request_file_diff` - 获取合并请求中特定文件的差异（必须提供 merge_request_iid 或 source_branch） 32. `list_merge_request_versions` - 列出合并请求的所有版本 33. `get_merge_request_version` - 获取合并请求的指定版本 34. `get_branch_diffs` - 获取两个分支或提交之间的差异 35. `update_merge_request` - 更新合并请求（必须提供 merge_request_iid 或 source_branch） 36. `create_note` - 为议题或合并请求创建新备注（评论） 37. `create_merge_request_thread` - 在合并请求中创建新讨论串 38. `resolve_merge_request_thread` - 解决合并请求中的讨论串 39. `mr_discussions` - 列出合并请求的讨论项 40. `get_merge_request_discussion` - 获取合并请求的单个讨论项 41. `delete_merge_request_discussion_note` - 删除合并请求中的讨论备注 42. `update_merge_request_discussion_note` - 更新合并请求中的讨论备注 43. `create_merge_request_discussion_note` - 向现有合并请求讨论串添加新备注 44. `create_merge_request_note` - 向合并请求添加新备注 45. `delete_merge_request_note` - 删除现有合并请求备注 46. `get_merge_request_note` - 获取合并请求的指定备注 47. `get_merge_request_notes` - 列出合并请求的备注 48. `update_merge_request_note` - 修改现有合并请求备注 49. `get_draft_note` - 获取合并请求的单个草稿备注 50. `list_draft_notes` - 列出合并请求的草稿备注 51. `create_draft_note` - 为合并请求创建草稿备注 52. `update_draft_note` - 更新现有草稿备注 53. `delete_draft_note` - 删除草稿备注 54. `publish_draft_note` - 发布单个草稿备注 55. `bulk_publish_draft_notes` - 发布合并请求的所有草稿备注。可选设置 reviewer_state 并发布摘要备注（GitLab 19.2+）。即使没有草稿，也可以设置 reviewer_state。 56. `list_merge_request_emoji_reactions` - 列出合并请求上的所有表情回应 57. `list_merge_request_note_emoji_reactions` - 列出合并请求备注上的所有表情回应。讨论串回复需传入 discussion_id。 58. `create_merge_request_emoji_reaction` - 为合并请求添加表情回应（例如 thumbsup、rocket、eyes） 59. `delete_merge_request_emoji_reaction` - 移除合并请求上的表情回应 60. `create_merge_request_note_emoji_reaction` - 为合并请求备注添加表情回应。讨论串回复需传入 discussion_id。 61. `delete_merge_request_note_emoji_reaction` - 移除合并请求备注上的表情回应。讨论串回复需传入 discussion_id。 62. `update_issue_note` - 修改现有议题讨论串备注 63. `create_issue_note` - 向议题添加备注，可选择回复讨论串 64. `list_issue_emoji_reactions` - 列出议题上的所有表情回应 65. `list_issue_note_emoji_reactions` - 列出议题备注上的所有表情回应。讨论串回复需传入 discussion_id。 66. `create_issue_emoji_reaction` - 为议题添加表情回应（例如 thumbsup、rocket、eyes） 67. `delete_issue_emoji_reaction` - 移除议题上的表情回应 68. `create_issue_note_emoji_reaction` - 为议题备注添加表情回应。讨论串回复需传入 discussion_id。 69. `delete_issue_note_emoji_reaction` - 移除议题备注上的表情回应。讨论串回复需传入 discussion_id。 70. `list_issues` - 列出议题（默认：由当前用户创建；使用 scope='all' 可列出全部） 71. `my_issues` - 列出分配给已认证用户的议题 72. `get_issue` - 获取指定议题的详情。默认返回仅含精简嵌套里程碑的议题；设置 full_response=true 可获取完整的里程碑对象 73. `update_issue` - 更新议题。默认返回精简确认信息；设置 full_response=true 可获取完整的更新后议题对象 74. `update_issue_description_patch` - 对议题描述应用补丁（搜索／替换或统一差异）。允许在不发送完整描述的情况下进行小幅修改，从而减少令牌用量。支持 dry_run 预览更改，并支持使用 create_note 总结更新内容。 75. `delete_issue` - 删除议题 76. `list_todos` - 列出当前用户的 GitLab 待办事项 77. `mark_todo_done` - 将 GitLab 待办事项标记为已完成 78. `mark_all_todos_done` - 将当前用户所有待处理的 GitLab 待办事项标记为已完成 79. `list_issue_links` - 列出指定议题的所有议题链接 80. `list_issue_discussions` - 列出议题的讨论 81. `get_issue_link` - 获取指定议题链接 82. `create_issue_link` - 在两个议题之间创建议题链接 83. `delete_issue_link` - 删除议题链接 84. `list_namespaces` - 列出当前用户可用的所有命名空间（用户和群组）。设置 kind='group' 可仅筛选群组。 85. `get_namespace` - 按 ID 或路径获取命名空间（用户或群组）的详情。kind='group' 的命名空间即为群组。 86. `verify_namespace` - 验证命名空间路径是否存在。使用 parent_id 可将检查限定到特定父命名空间；对于可能在不同父级下存在相同路径的嵌套命名空间，此参数为必填。 87. `get_project` - 获取指定项目的详情 88. `list_projects` - 列出当前用户可访问的项目 89. `update_project` - 更新项目设置，例如描述、可见性、默认分支和功能访问级别 90. `list_project_members` - 列出 GitLab 项目成员 91. `list_group_members` - 列出 GitLab 群组成员，可选按名称或用户名搜索 92. `list_labels` - 列出项目标签 93. `get_label` - 获取项目的单个标签 94. `create_label` - 在项目中创建新标签 95. `update_label` - 更新项目中的现有标签 96. `delete_label` - 删除项目标签 97. `list_group_projects` - 列出群组中的项目 98. `list_wiki_pages` - 列出项目中的 Wiki 页面 99. `get_wiki_page` - 获取指定 Wiki 页面的详情 100. `create_wiki_page` - 在项目中创建 Wiki 页面 101. `update_wiki_page` - 更新项目中的 Wiki 页面 102. `delete_wiki_page` - 从项目中删除 Wiki 页面 103. `list_group_wiki_pages` - 列出群组中的 Wiki 页面 104. `get_group_wiki_page` - 获取指定群组 Wiki 页面的详情 105. `create_group_wiki_page` - 在群组中创建 Wiki 页面 106. `update_group_wiki_page` - 更新群组中的 Wiki 页面 107. `delete_group_wiki_page` - 从群组中删除 Wiki 页面 108. `get_repository_tree` - 列出仓库中的文件和目录 109. `list_pipelines` - 列出流水线，支持筛选选项 110. `get_pipeline` - 获取指定流水线的详情 111. `get_pipeline_variables` - 获取为流水线配置的变量 112. `get_pipeline_test_report` - 获取流水线测试报告 113. `get_pipeline_test_report_summary` - 获取流水线测试报告摘要 114. `delete_pipeline` - 删除流水线。需要项目 Owner 角色，无法撤销，且不会自动删除子流水线。 115. `update_pipeline_metadata` - 更新流水线元数据 116. `list_deployments` - 列出部署，支持筛选选项 117. `get_deployment` - 获取部署详情；GitLab 提供时还包括 approval_summary、approvals 和 pending_approval_count 118. `create_deployment` - 创建部署 119. `update_deployment` - 更新部署状态 120. `delete_deployment` - 删除部署 121. `list_deployment_merge_requests` - 列出随部署发布的合并请求 122. `approve_deployment` - 批准或拒绝受保护环境的部署 123. `list_environments` - 列出项目中的环境 124. `get_environment` - 获取指定环境的详情 125. `update_environment` - 更新环境 126. `delete_environment` - 删除已停止的环境 127. `stop_environment` - 停止环境 128. `stop_stale_environments` - 停止符合条件的过期环境；受保护环境会被排除，环境只会停止而不会删除 129. `delete_review_app_environments` - 安排在一周后删除已停止的审查应用环境；dry_run 默认为 true，实际安排删除需设置 dry_run=false 130. `list_pipeline_triggers` - 列出项目流水线触发令牌 131. `get_pipeline_trigger` - 获取项目流水线触发器 132. `create_pipeline_trigger` - 创建项目流水线触发器 133. `update_pipeline_trigger` - 更新项目流水线触发器 134. `delete_pipeline_trigger` - 删除项目流水线触发器 135. `trigger_pipeline` - 使用流水线触发令牌触发流水线 136. `list_pipeline_jobs` - 列出指定流水线中的所有作业 137. `list_pipeline_trigger_jobs` - 列出流水线中的触发作业（桥接作业） 138. `get_pipeline_job` - 获取 GitLab 流水线作业编号的详情 139. `get_pipeline_job_output` - 获取流水线作业跟踪日志，支持从末尾分页，或对完整日志进行子字符串／正则表达式搜索 140. `validate_ci_lint` - 验证为项目提供的 GitLab CI/CD YAML 内容 141. `validate_project_ci_lint` - 验证项目现有的 .gitlab-ci.yml 配置 142. `list_ci_catalog_resources` - 列出用户可见的 GitLab CI/CD Catalog 资源／组件 143. `get_ci_catalog_resource` - 获取 GitLab CI/CD Catalog 资源的详情，包括版本和组件 144. `create_pipeline` - 为分支或标签创建新流水线 145. `retry_pipeline` - 重试失败或已取消的流水线 146. `cancel_pipeline` - 取消正在运行的流水线 147. `list_pipeline_schedules` - 列出项目中的流水线计划，可选按启用或停用状态筛选 148. `get_pipeline_schedule` - 获取指定流水线计划的详情，包括其变量和最近一次流水线 149. `list_pipeline_schedule_pipelines` - 列出流水线计划触发的流水线 150. `create_pipeline_schedule` - 为分支或标签创建新的流水线计划 151. `update_pipeline_schedule` - 更新现有流水线计划 152. `delete_pipeline_schedule` - 删除流水线计划 153. `play_pipeline_schedule` - 立即运行流水线计划 154. `take_ownership_pipeline_schedule` - 接管流水线计划 155. `get_pipeline_schedule_variable` - 获取流水线计划的单个变量 156. `create_pipeline_schedule_variable` - 为流水线计划创建变量 157. `update_pipeline_schedule_variable` - 更新流水线计划的变量 158. `delete_pipeline_schedule_variable` - 删除流水线计划中的变量 159. `play_pipeline_job` - 运行手动流水线作业 160. `play_pipeline_jobs` - 依次运行多个手动流水线作业 161. `retry_pipeline_job` - 重试失败或已取消的流水线作业 162. `cancel_pipeline_job` - 取消正在运行的流水线作业 163. `erase_pipeline_job` - 清除流水线作业日志和制品 164. `wait_for_pipeline` - 等待流水线达到终止状态 165. `wait_for_job` - 等待作业达到终止状态 166. `list_job_artifacts` - 列出作业归档中的制品文件 167. `download_job_artifacts` - 下载作业制品归档（zip）并保存到下载目录 168. `get_job_artifact_file` - 获取作业制品中的单个文件内容 169. `list_merge_requests` - 列出合并请求（不提供 project_id：用户的合并请求；提供 project_id：项目的合并请求） 170. `list_group_merge_requests` - 列出群组及其子群组所有项目中的合并请求 171. `list_milestones` - 列出里程碑，支持筛选选项 172. `get_milestone` - 获取指定里程碑的详情 173. `create_milestone` - 创建新里程碑 174. `edit_milestone` - 编辑现有里程碑 175. `delete_milestone` - 删除里程碑 176. `get_milestone_issue` - 获取与指定里程碑关联的议题 177. `get_milestone_merge_requests` - 获取与指定里程碑关联的合并请求 178. `promote_milestone` - 将里程碑推进到下一阶段 179. `get_milestone_burndown_events` - 获取指定里程碑的燃尽事件 180. `list_group_milestones` - 列出群组里程碑，支持筛选选项 181. `get_group_milestone` - 获取指定群组里程碑的详情 182. `create_group_milestone` - 创建新的群组里程碑 183. `edit_group_milestone` - 编辑现有群组里程碑 184. `delete_group_milestone` - 删除群组里程碑 185. `get_group_milestone_issue` - 获取与指定群组里程碑关联的议题 186. `get_group_milestone_merge_requests` - 获取与指定群组里程碑关联的合并请求 187. `get_group_milestone_burndown_events` - 获取指定群组里程碑的燃尽事件 188. `get_users` - 按用户名获取 GitLab 用户详情 189. `get_user` - 按 ID 获取用户详情 190. `whoami` - 获取当前已认证用户的详情 191. `list_commits` - 列出仓库提交，支持筛选选项 192. `get_commit` - 获取指定提交的详情 193. `get_commit_diff` - 获取指定提交的更改／差异 194. `get_file_blame` - 获取文件在指定 ref 下的 git blame 信息。每个条目将连续的源代码行范围映射到最近一次更改它们的提交（id、author、authored_date、message）。使用 range_start/range_end 可将 blame 限定到特定行。 195. `list_commit_statuses` - 列出提交的状态 196. `create_commit_status` - 创建或更新提交的状态 197. `list_group_iterations` - 列出群组迭代，支持筛选选项 198. `upload_markdown` - 上传供 Markdown 内容使用的文件 199. `download_attachment` - 从项目下载已上传文件（图像以 base64 返回；其他文件或指定 local_path 的图像会作为新文件保存到下载目录） 200. `health_check` - 验证服务状态和身份验证。始终报告 MCP 服务版本（mcp_server_version）。通过身份验证后，还会报告 GitLab 实例版本，来自 GET /api/v4/version（version、revision、enterprise）。版本查询失败不会导致健康检查失败；相应字段将被省略。 201. `list_events` - 列出已认证用户的事件（before/after：YYYY-MM-DD） 202. `get_project_events` - 列出项目事件（before/after：YYYY-MM-DD） 203. `list_releases` - 列出项目的所有发行版 204. `get_release` - 按标签名称获取发行版 205. `create_release` - 创建新发行版 206. `update_release` - 更新现有发行版 207. `delete_release` - 删除发行版（不会删除标签） 208. `create_release_evidence` - 创建发行版证据（Premium/Ultimate） 209. `download_release_asset` - 按直接资源路径下载发行版资源文件 210. `list_tags` - 列出项目的仓库标签 211. `get_tag` - 按名称获取仓库标签 212. `create_tag` - 创建新仓库标签 213. `delete_tag` - 删除仓库标签 214. `get_tag_signature` - 获取已签名标签的 X.509 签名（未签名时返回 404） 215. `list_protected_tags` - 列出项目中的受保护标签 216. `get_protected_tag` - 获取单个受保护标签或通配符的详情（创建访问级别） 217. `protect_tag` - 保护仓库标签或通配符（设置谁可以创建它） 218. `unprotect_tag` - 取消先前受保护标签或通配符的保护 219. `get_work_item` - 获取工作项的完整详情，包括状态、层级、类型和小组件 220. `list_work_items` - 列出工作项，支持筛选（类型、状态、搜索、受分配者、标签） 221. `create_work_item` - 创建工作项（议题、任务、事件、史诗等），支持完整字段 222. `update_work_item` - 更新工作项（标题、描述、标签、受分配者、状态、父级、自定义字段等） 223. `convert_work_item_type` - 将工作项转换为其他类型 224. `list_work_item_statuses` - 列出工作项类型可用的状态（Premium/Ultimate） 225. `list_custom_field_definitions` - 列出工作项类型的自定义字段定义 226. `move_work_item` - 将工作项移动到其他项目 227. `list_work_item_notes` - 列出工作项的备注和讨论 228. `create_work_item_note` - 向工作项添加备注（支持 Markdown、内部备注和讨论串） 229. `list_work_item_emoji_reactions` - 列出工作项上的所有表情回应 230. `list_work_item_note_emoji_reactions` - 列出工作项备注上的所有表情回应（评论、讨论串或讨论串回复） 231. `create_work_item_emoji_reaction` - 为工作项添加表情回应（例如 thumbsup、rocket、eyes） 232. `delete_work_item_emoji_reaction` - 移除工作项上的表情回应 233. `create_work_item_note_emoji_reaction` - 为工作项备注添加表情回应（评论、讨论串或讨论串回复） 234. `delete_work_item_note_emoji_reaction` - 移除工作项备注上的表情回应（评论、讨论串或讨论串回复） 235. `get_timeline_events` - 列出事件的时间线事件 236. `create_timeline_event` - 在事件中创建时间线事件 237. `list_webhooks` - 列出项目或群组的 Webhook 238. `create_webhook` - 在项目或群组中创建 Webhook 239. `update_webhook` - 更新现有项目或群组 Webhook 240. `delete_webhook` - 删除项目或群组 Webhook 241. `list_webhook_events` - 列出最近的 Webhook 事件（过去 7 天） 242. `get_webhook_event` - 获取指定 Webhook 事件的完整详情 243. `search_code` - 跨所有项目搜索代码（需要高级搜索或 Zoekt） 244. `search_project_code` - 在指定项目中搜索代码（需要高级搜索或 Zoekt） 245. `search_group_code` - 在指定群组中搜索代码（需要高级搜索或 Zoekt） 246. `list_project_variables` - 列出项目的 CI/CD 变量 247. `get_project_variable` - 获取项目中的单个 CI/CD 变量 248. `create_project_variable` - 为项目创建 CI/CD 变量 249. `update_project_variable` - 更新项目中的现有 CI/CD 变量 250. `delete_project_variable` - 删除项目中的 CI/CD 变量 251. `list_group_variables` - 列出群组的 CI/CD 变量 252. `get_group_variable` - 获取群组中的单个 CI/CD 变量 253. `create_group_variable` - 为群组创建 CI/CD 变量 254. `update_group_variable` - 更新群组中的现有 CI/CD 变量 255. `delete_group_variable` - 删除群组中的 CI/CD 变量 256. `get_dependency_proxy_settings` - 获取群组的依赖代理设置 257. `update_dependency_proxy_settings` - 更新群组的依赖代理设置（启用／禁用、用于从经过身份验证的 Docker Hub 拉取内容的凭据） 258. `list_dependency_proxy_blobs` - 列出群组缓存的依赖代理 Blob 259. `purge_dependency_proxy_cache` - 安排清除群组所有缓存的依赖代理 Blob 260. `list_project_vulnerabilities` - 列出项目的漏洞，可选按状态、严重程度和报告类型筛选（基于 GraphQL，游标分页） 261. `get_vulnerability` - 获取指定漏洞的完整详情 262. `dismiss_vulnerability` - 以指定原因（acceptable_risk、false_positive、used_in_tests、mitigating_control、not_applicable）忽略漏洞，并可添加评论 263. `confirm_vulnerability` - 确认漏洞为需要修复的真实发现 264. `orbit_query` - 在已索引的 SDLC 知识图谱上执行 GitLab Orbit 图查询 265. `orbit_get_schema` - 获取当前 GitLab Orbit 图谱架构（节点和边类型） 266. `orbit_get_status` - 检查已启用范围的 GitLab Orbit 索引状态 267. `orbit_list_tools` - 列出 GitLab Orbit 提供的 MCP 工具定义 268. `list_snippets` - 列出代码片段——提供 project_id 时列出项目代码片段，否则列出个人代码片段 269. `get_snippet` - 获取代码片段的元数据。设置 include_content=true 还可获取原始文件内容。 270. `create_snippet` - 创建代码片段——提供 project_id 时创建项目级代码片段，否则创建个人代码片段。需要 title，以及 file_name + content（单文件）或 files[]（多文件）；两种结构不能混用。 271. `update_snippet` - 更新现有代码片段（至少提供一个要更改的字段）。编辑多个文件（重命名、删除、添加）时，传入带有 action（create/update/delete/move）和 previous_path 的 files[]。单文件内容替换仍可使用 file_name + content 快捷方式。 272. `delete_snippet` - 删除代码片段 273. `list_project_runners` - 列出项目可用的 Runner（type、status、paused、tag_list）。不包含注册令牌和身份验证令牌。 274. `get_runner` - 获取 Runner 的 tag_list、run_untagged、locked 和 access_level。如果项目启用了允许列表，该 Runner 必须对允许列表中的某个项目可用。不包含注册令牌和身份验证令牌。 275. `rebase_merge_request` - 将合并请求的源分支变基到目标分支 276. `gitlab_api_request` - 在 /api/v4 下发送一次 GitLab REST 调用。仅当 GITLAB_TOOLSETS 列出 api 时启用。Readonly 仅允许 GET；modify 会拒绝 DELETE。 277. `discover_tools` - 为此会话发现并启用其他工具类别。可用类别：core、merge_requests、issues、repositories、branches、projects、labels、ci、groups、pipelines、milestones、wiki、releases、tags、snippets、users、workitems、webhooks、search、variables、dependency_proxy、vulnerabilities、orbit。响应中会列出已启用的类别。 278. `help` - 返回简短的 GitLab 工作流指南。省略 topic 可查看概览和主题列表。

Wiki 页面标题与 slug

GitLab 会根据页面标题生成 Wiki 页面的 slug（其 URL 为 /-/wikis/<slug>）。因此，向 update_wiki_page / update_group_wiki_page 传入 title 会重命名页面并更改其 URL；对于嵌套页面，还可能将页面移至其他路径，从而导致现有链接失效。

若要仅更改显示的标题并保持 URL 不变，请勿传入 title。请改为将显示标题存储在页面内容的 YAML front matter 中，并更新内容：

---
title: My Custom Display Title
---

Page body…

GitLab 会保持 slug/URL 不变，并在界面中显示 front matter 中的标题。使用 get_wiki_page 并设置 render_html: true 可读取该标题，此时会填充 front_matter 字段；普通的 title 字段始终反映根据 slug 生成的值。

测试 🧪

该项目包含全面的测试覆盖，包括远程授权：

# Run all tests (API validation + remote auth)
npm test

# Run only remote authorization tests
npm run test:remote-auth

# Run all tests including readonly MCP tests
npm run test:all

# Run only API validation
npm run test:integration

所有远程授权测试均使用模拟的 GitLab 服务，无需实际的 GitLab 凭据。