gitlab-mcp

gitlab-mcp

适用于 gitlab.com 的 MCP 服务。一个通过标准输入输出通信的二进制程序，以你的身份登录。 它在项目内运行：处理议题、 合并请求、评审、代码库和 CI。不涉及实例和群组管理、Runner、CI 变量和令牌。

这是非官方项目，与 GitLab Inc. 无关。请参阅 NOTICE。

有何不同

• 范围精简，通过注册控制。 大约提供六十种工具， 而非镜像整个 API；关闭的工具不会注册， 因此完全无法调用。
• 不会执行写入内容中的快速操作。 评论中的 /merge 会被 拒绝或转义，绝不会执行。
• 内容会标记为不可信。 议题、评审、文件和作业 日志都会放在内容无法关闭的边界内返回。
• 像桌面应用一样登录。 使用你自己的 OAuth 应用、浏览器 标签页，以及操作系统钥匙串中的令牌。
• 可验证的发行版本。 提供签名校验和、构建来源证明和 SBOM。

状态

稳定：上方的发行版本徽章显示最新标签， CHANGELOG.md 说明每个版本包含的内容。工具接口是一种 契约：工具会保留其名称和输出字段。 docs/architecture.md §16 是规划方案。

工具

工具	功能
get_me	查看谁已登录、拥有哪些权限范围，以及 GitLab 对自身的报告
resolve_url	将 GitLab 网页 URL 转换为其他工具所需的参数，并指出该工具
search_projects	按名称或在某个群组中查找项目
get_project	查看单个项目：默认分支、可见性和已启用的功能
list_members	查看谁有权访问某个项目，以及各自的角色
find_users	按确切用户名或姓名查找账户
search_issues	在 gitlab.com、某个群组或项目中查找议题
get_issue	查看单个议题、标记为不可信内容的描述，以及关联的合并请求
create_issue	创建议题；先检查标签、指派对象和里程碑
update_issue	更改议题字段；如果议题在读取后发生变化，则拒绝操作
list_discussions	查看议题或合并请求中的评论讨论串
list_item_events	按时间倒序查看议题或合并请求的标签、状态、里程碑和权重变更
add_comment	评论议题或合并请求、在讨论串中回复或发起讨论串，也可以在差异行上评论
update_comment	在原处编辑你自己的评论，保留其讨论串和差异行位置
resolve_discussion	解决或重新打开合并请求或议题中的讨论串
link_issues	关联两个议题，可以来自同一个或两个不同的项目
unlink_issues	移除两个议题之间的关联
link_merge_requests	设置一个合并请求等待另一个合并，可以来自同一个或两个不同的项目
unlink_merge_requests	移除两个合并请求之间的依赖关系
search_merge_requests	在 gitlab.com 或某个项目中查找合并请求
get_merge_request	查看单个合并请求及其审批、审阅者状态、关联议题和依赖关系
list_mr_files	查看合并请求修改的文件、行数以及 GitLab 的标记
get_mr_diff	按文件查看合并请求的差异，结果有上限
list_mr_commits	查看合并请求的提交
list_mr_versions	查看合并请求的差异版本，每次推送对应一个版本
compare_mr_versions	查看合并请求两个版本之间或某个版本之后的变更
create_merge_request	从分支创建合并请求
update_merge_request	更改合并请求字段；如果合并请求在读取后发生变化，则拒绝操作
track_time	设置或重置议题或合并请求的时间估算，并添加或重置已用时间
add_review_comment	在合并请求上或差异行上添加审阅草稿评论
list_review_comments	查看你在合并请求上尚未发布的审阅评论
delete_review_comment	删除你的一条草稿评论
update_review_comment	更改你的一条草稿评论的文本，同时保留其位置
publish_review_comment	单独发布你的一条草稿评论
submit_review	一次性发布你的所有草稿，并附上摘要和审阅者状态
rerequest_review	在审阅者要求的更改完成后，请求其重新审阅
get_file	查看某个引用处的文件，结果有上限
list_tree	查看某个引用处的目录列表
list_branches	查看项目的分支
list_commits	查看某个引用或路径上的提交
get_commit	查看单个提交及其差异（结果有上限），以及包含该提交的合并请求
compare_refs	查看两个引用之间的提交和差异，结果有上限
list_tags	查看项目的标签
create_branch	从某个引用创建分支
create_commit	将文件变更提交到分支；绝不提交到默认分支或受保护分支
get_blame	查看文件每一行的最近修改者，结果有上限
cherry_pick_commit	将提交应用到分支；绝不应用到默认分支或受保护分支
revert_commit	在分支上创建一个新提交以撤销某个提交；绝不操作默认分支或受保护分支
list_pipelines	查看项目的 CI 流水线
get_pipeline	查看单条流水线及失败的作业，包括触发作业
list_jobs	查看流水线的作业
get_job_log	查看作业日志的一段内容，密钥会被遮蔽；也可按请求查看失败部分
get_test_report	查看流水线的测试数量和失败用例，密钥会被遮蔽，结果有上限
lint_ci	检查项目在某个引用处的 CI 配置，或检查你提供的配置
list_job_artifacts	查看作业保留的工件文件
get_job_artifact	查看作业工件中的一个文本文件，密钥会被遮蔽，结果有上限
list_labels	查看项目议题和合并请求可使用的标签
list_milestones	查看项目或群组的里程碑
list_boards	查看项目的议题看板及其列表，每个列表都附有用于读取它的 search_issues 参数
search	在某个项目、群组或所有位置搜索代码、提交、评论等
list_todos	查看你的待办事项
mark_todos_done	将你的待办事项标记为已完成
add_todo	在议题或合并请求上为自己添加待办事项
subscribe	订阅或取消订阅议题或合并请求的通知
react	在议题、合并请求或评论上添加或移除你的表情回应
upload_file	从你允许访问的目录上传图片，并获取可在评论或描述中显示该图片的 Markdown
merge_merge_request	按你审阅过的最新提交合并，或在流水线成功时合并（Ship）
cancel_auto_merge	停止在流水线成功时合并合并请求（Ship）
approve_merge_request	批准你审阅过的最新提交（Ship）
unapprove_merge_request	撤回你的批准（Ship）
apply_suggestions	将合并请求差异评论中的建议提交到其源分支；绝不提交到受保护分支（Ship）
rebase_merge_request	根据你审阅过的最新提交变基合并请求的源分支（Ship）
move_issue	将议题移至另一个项目；绝不移至更多人可见的项目（Ship）
run_pipeline	为某个引用运行流水线；变量值永不显示（Ship）
run_merge_request_pipeline	运行合并请求的流水线，由 GitLab 选择合并结果或分离模式；不适用于分叉项目的合并请求（Ship）
retry_pipeline	重试流水线中失败和已取消的作业（Ship）
retry_job	使用输入重新运行已结束的作业（Ship）
play_job	使用变量和输入启动手动作业（Ship）
cancel_pipeline	取消正在运行的流水线（Ship）
delete_branch	删除分支；除非用户要求，否则绝不删除默认分支、受保护分支或尚未合并的分支（Destructive）
delete_comment	删除你自己的评论（Destructive）
make_issue_public	将机密议题设为公开（Destructive）
list_wiki_pages	查看项目 Wiki 页面（wiki 工具集）
get_wiki_page	查看单个 Wiki 页面，结果有上限（wiki 工具集）
save_wiki_page	创建 Wiki 页面，或修改自读取后未变更的页面（wiki 工具集）
delete_wiki_page	删除 Wiki 页面（wiki 工具集，Destructive）
list_snippets	查看项目代码片段或你自己的代码片段（snippets 工具集）
get_snippet	查看单个代码片段及其文件，结果有上限（snippets 工具集）
create_snippet	创建代码片段，始终为私有（snippets 工具集）
update_snippet	修改你自己的私有代码片段：标题、描述和文件；如果代码片段在读取后发生变化，则拒绝操作（snippets 工具集）
delete_snippet	删除你自己的代码片段（snippets 工具集，Destructive）
list_releases	查看项目的发行版（releases 工具集）
get_release	查看单个发行版及其说明（releases 工具集）
create_release	创建发行版及其在某个引用处的标签，并添加指向项目自有页面的资源链接（releases 工具集，Ship）
create_tag	在某个引用处创建标签；绝不创建受保护标签（releases 工具集）
delete_tag	删除标签；绝不删除受保护标签（releases 工具集，Destructive）
create_label	创建项目标签（planning 工具集）
update_label	修改自读取后未变更的项目标签（planning 工具集）
delete_label	删除项目标签（planning 工具集，Destructive）
create_milestone	创建项目里程碑（planning 工具集）
update_milestone	修改、关闭或重新打开自读取后未变更的里程碑（planning 工具集）
delete_milestone	删除项目里程碑（planning 工具集，Destructive）
list_environments	查看项目的环境及其最近一次部署（deployments 工具集）
list_deployments	查看部署内容、部署位置以及执行部署的作业（deployments 工具集）
list_events	查看你自己的近期活动或项目的近期活动（activity 工具集）
只有在下方设置中注册 Ship 和 Destructive 工具，
并且只有当 GITLAB_MCP_TOOLSETS 指定六个工具集时，才会注册它们。

三个资源包含相同的文本，供选择附加而非调用的客户端使用：一个议题、一项合并请求和一份作业日志。

安装

从发布页面下载适用于你平台的压缩包，或：

go install github.com/mmedum/gitlab-mcp/v4/cmd/gitlab-mcp@latest

Claude Desktop 用户可以打开同一版本发布内容中的 .mcpb 包。 它不会为你登录；请先完成以下步骤。

登录

你需要使用自己的 OAuth 应用。二进制文件中不包含任何应用，也不使用个人访问令牌。

1. 注册应用，只需一次。在 gitlab.com 上：点击你的头像 → 编辑个人资料 → 应用程序（或某个群组的应用程序）。重定向 URI 为 http://127.0.0.1/callback，取消勾选 Confidential，作用域为 api （只读时使用 read_api）。docs/setup.md 列出了确切值。

2. 从终端登录：

   gitlab-mcp login --client-id <application id>
   

   它会显示将请求的作用域，打开浏览器，并将令牌存储在操作系统密钥环中。在没有浏览器的机器上，--no-browser 会显示 URL 和用于转发回调的 ssh -L 命令。

3. 检查登录状态：

   gitlab-mcp doctor
   

   doctor 会检查连接、TLS、登录状态、应用、已授予的作用域以及以你的身份进行的一次调用，并指出缺少的内容。 status 和 logout 分别执行其名称所示的操作；--profile 可让两个 gitlab.com 登录配置并存。

连接客户端

Claude Code：

claude mcp add gitlab -- gitlab-mcp

任何支持 JSON 服务列表的客户端：

{
  "mcpServers": {
    "gitlab": { "command": "gitlab-mcp" }
  }
}

Claude Desktop 也可以直接打开版本发布内容中的 .mcpb 包。 它会询问相同的设置：合并、批准、应用建议、移动议题、CI 和发布（enable_ship），以及删除（enable_destructive）默认关闭，除非你主动启用；write_namespaces 会将写入操作限制在你指定的群组和项目中。 此服务不会在调用前征求任何人的确认。Claude Desktop 会逐个批准工具，而你设置为始终允许的工具之后会在未经询问的情况下运行，因此除非需要使用相应工具，否则请保持开关关闭。

配置

每项设置都是一个带有 GITLAB_MCP_ 前缀且对应一个标志的环境变量。docs/configuration.md 列出了全部设置。

安全性

GitLab 内容由他人编写，其中一些内容可能意在引导 Agent。服务会将其标记为不可信数据，不会获取其中引用的内容，也不会将其添加的任何内容作为指示模型采取行动的指令。

可注册的内容取决于设置，因为 GitLab 的 api scope 无法区分这些内容：

设置	注册内容
GITLAB_MCP_READ_ONLY=true	仅注册读取工具，使用 read_api 令牌
默认	读取和写入：议题、评论、评审、分支、合并请求
GITLAB_MCP_ENABLE_SHIP=true	添加合并、批准、运行 CI 和发布功能
GITLAB_MCP_ENABLE_DESTRUCTIVE=true	添加删除和将议题设为公开的功能，且每次调用都必须传入 confirm: true

MCP 客户端会逐次批准调用；服务本身不会向你请求批准。claude.ai 和 Codex 会针对 Ship 和 Destructive 工具提示确认，这些工具被标记为破坏性工具；VS Code 则会针对每个写入工具提示确认。在 Claude Code 中，无论你的规则如何设置，delete_label、delete_milestone 和 make_issue_public 每次调用都会请求确认，因为这些操作无法撤销，且影响范围不止单个项目：标签或里程碑会从所有议题和合并请求中移除，公开议题则人人可读。对于其他操作，请在设置中的 permissions.ask 下逐一列出你想批准的调用，并将 gitlab 替换为你为服务指定的名称。例如，执行交付、发布、上传或删除的写入操作：

{
  "permissions": {
    "ask": [
      "mcp__gitlab__merge_merge_request", "mcp__gitlab__approve_merge_request",
      "mcp__gitlab__apply_suggestions", "mcp__gitlab__run_pipeline",
      "mcp__gitlab__run_merge_request_pipeline", "mcp__gitlab__play_job",
      "mcp__gitlab__create_release", "mcp__gitlab__create_tag", "mcp__gitlab__move_issue",
      "mcp__gitlab__upload_file",
      "mcp__gitlab__delete_branch", "mcp__gitlab__delete_comment",
      "mcp__gitlab__delete_wiki_page", "mcp__gitlab__delete_label",
      "mcp__gitlab__delete_milestone", "mcp__gitlab__delete_tag",
      "mcp__gitlab__delete_snippet"
    ]
  }
}

• 不执行快捷操作。 GitLab 会从描述或评论中执行 /merge、/close 等命令。此服务发送的每个正文都会经过检查；其中的快捷操作行会被拒绝，或者在你要求时进行转义。
• 保护分支。 代码只能通过合并请求进入默认分支或受保护分支；直接提交到这些分支会被拒绝。
• 不盲目重试。 对于可能已成功、也可能未成功的创建操作，会通过读取来确认结果，而不会再次创建。
• 仅从你允许的位置读取本地文件。 upload_file 只会从 GITLAB_MCP_UPLOAD_DIRS 指定的目录中读取图像，并根据其字节内容判断是否为 PNG、JPEG、GIF 或 WebP。因此，评论中要求“附上”密钥文件也不会奏效。

默认令牌仍可用于合并和批准；关闭 Ship 只会阻止此服务执行这些操作，不会限制任何其他持有该令牌的对象。 更多信息请参阅 docs/security.md。

验证发布版本

每个发布版本都会使用无密钥 Sigstore 证书对 checksums.txt 签名，并对每个归档文件和软件包进行证明：

sha256sum -c checksums.txt --ignore-missing
cosign verify-blob checksums.txt --bundle checksums.txt.bundle \
  --certificate-identity "https://github.com/mmedum/gitlab-mcp/.github/workflows/release.yml@refs/tags/<tag>" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com
gh attestation verify <archive> --repo mmedum/gitlab-mcp

贡献

请参阅 CONTRIBUTING.md。安全问题请通过 SECURITY.md 报告，不要提交议题。

许可证

Apache-2.0。请参阅 LICENSE 和 NOTICE。