Gerrit Code Review

go-gerrit-mcp

一个 MCP（Model Context Protocol）服务，可将 Gerrit 代码审查操作作为由能力门控的工具提供。AI Agent 可以搜索和读取变更、发布审查评论、投票并推动变更状态转换。每项写入能力都必须由操作者明确选择启用。

• 传输方式：stdio
• 目标平台：Gerrit 3.13+，通过 HTTP 凭据进行身份验证
• 输出：llmxml，一种带语义标签、供模型阅读的文本（参见输出格式）

安全策略

两个默认设置体现了这一策略：

• 零配置时仅开放 read 组。除非通过 --groups 启用，否则不会提供写入能力。
• 默认启用仅限本人变更的限制。即使启用了写入组，对于经过身份验证的账号不拥有的变更，也会拒绝可能留下痕迹的操作（评论、投票、状态变更，以及其他人可见的任何操作），除非操作者明确传入 --own-changes-only=false。

AI Agent 在同事的变更上留下不想要的痕迹，是外部可见的失败；缺少某项能力则是可在本地发现的不便。因此采用了这些默认设置。请谨慎扩大权限：

# agent may comment and vote on anyone's changes, but only within two projects
go-gerrit-mcp --groups read,comment,transition --own-changes-only=false --projects core,infra

安装

二进制发行版：从 GitHub Releases 下载适用于你平台的二进制文件，将其设为可执行文件，并放入你的 PATH：

# macOS on Apple silicon; substitute <os>_<arch> from: linux, darwin, windows x amd64, arm64
curl -Lo /usr/local/bin/go-gerrit-mcp \
  https://github.com/GaijinEntertainment/go-gerrit-mcp/releases/latest/download/go-gerrit-mcp_darwin_arm64
chmod +x /usr/local/bin/go-gerrit-mcp

Docker：

docker pull ghcr.io/gaijinentertainment/go-gerrit-mcp:latest

go install：

go install dev.gaijin.team/go/go-gerrit-mcp/cmd/go-gerrit-mcp@latest

快速开始

服务仅从环境变量读取连接身份信息；凭据不会通过标志传递：

变量	含义
GERRIT_URL	Gerrit 实例的基础 URL
GERRIT_USERNAME	用于 HTTP Basic 身份验证的账号用户名
GERRIT_TOKEN	与用户名配对的 HTTP 凭据

在 Gerrit 的 设置 → HTTP 凭据 中生成凭据（HTTP 密码，或在提供此类凭据的实例中使用身份验证令牌）。三个变量都必须设置；缺少变量时，服务会退出并指出缺少的变量。

Claude Code

claude mcp add gerrit \
  --env GERRIT_URL=https://gerrit.example.com \
  --env GERRIT_USERNAME=your-username \
  --env GERRIT_TOKEN=your-http-credential \
  -- go-gerrit-mcp

任意 MCP 客户端（JSON 配置）

{
  "mcpServers": {
    "gerrit": {
      "command": "go-gerrit-mcp",
      "args": ["--groups", "read"],
      "env": {
        "GERRIT_URL": "https://gerrit.example.com",
        "GERRIT_USERNAME": "your-username",
        "GERRIT_TOKEN": "your-http-credential"
      }
    }
  }
}

Docker

{
  "mcpServers": {
    "gerrit": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "GERRIT_URL", "-e", "GERRIT_USERNAME", "-e", "GERRIT_TOKEN",
        "ghcr.io/gaijinentertainment/go-gerrit-mcp:latest",
        "--groups", "read"
      ],
      "env": {
        "GERRIT_URL": "https://gerrit.example.com",
        "GERRIT_USERNAME": "your-username",
        "GERRIT_TOKEN": "your-http-credential"
      }
    }
  }
}

Claude Code 中的项目级配置

服务所需的一切都从环境中读取：上述身份变量，以及与每个标志对应的 GERRIT_MCP_* 镜像变量（参见配置参考）。MCP 服务进程会继承会话环境，因此在 Claude Code 中，一次用户级注册即可实现项目级配置，甚至可为不同仓库配置使用不同凭据的 Gerrit 实例。

~/.claude.json 保存注册信息，不包含 env 块：

{
  "mcpServers": {
    "gerrit": {
      "command": "go-gerrit-mcp"
    }
  }
}

<project>/.claude/settings.local.json 保存项目环境；其中每个 env 条目都会传递给服务进程：

{
  "env": {
    "GERRIT_URL": "https://gerrit.example.com",
    "GERRIT_USERNAME": "your-username",
    "GERRIT_TOKEN": "your-http-credential",
    "GERRIT_MCP_GROUPS": "read,comment",
    "GERRIT_MCP_PROJECTS": "core,infra"
  }
}

大多数项目共用的值可以放在上一层的 ~/.claude/settings.json 中。设置文件会合并，优先级为 .claude/settings.local.json 高于 .claude/settings.json，后者又高于 ~/.claude/settings.json，因此项目只需声明自己的差异项。若没有任何层设置某项值，则使用服务自身的默认值：只读、仅限本人变更。

注册中的 env 块保持为空是有原因的。在此处命名的变量会覆盖所有设置层；引用也无法绕过此限制：${VAR} 只会从启动 claude 的 shell 环境中展开，不会从设置文件中展开；任何未解析的内容都会以字面字符串的形式传递给服务。

其他 MCP 客户端也会以同样方式继承其启动环境，因此，direnv 这类按目录配置的工具无需客户端支持，也能实现相同的配置隔离。

能力组

通过 --groups 以逗号分隔的列表在启动时选择能力组。各组彼此独立且可组合，没有权限等级：每个可写组都会包含其独立工作所需的最小变更读取子集，启用的组会取并集。

组	工具
read	search_changes、get_change、list_change_files、get_file_diff、get_change_comments
comment	get_change、get_change_comments、post_comments
transition	get_change、set_vote、transition_change

工具

• search_changes：使用 Gerrit 的变更查询语法查询变更，支持分页。
• get_change：获取一项变更中与评审相关的详细信息：状态、所有者、带投票的标签、当前修订版和消息。
• list_change_files：列出某个修订版修改的文件及每个文件的变更统计信息。
• get_file_diff：获取某个修订版中一个文件的差异。
• get_change_comments：获取变更的评论串，包括解决状态和评论 ID。默认仅返回未解决的评论串；status=all 获取完整历史记录，status=resolved 获取已解决的评论串。
• post_comments：一次调用即可发布评审内容：可选的顶层消息，以及行内、范围、文件级和回复评论。回复以 get_change_comments 返回的评论 ID 为锚点；resolved 可切换评论串状态。
• set_vote：设置标签投票（例如 Code-Review），并可附带消息；值为 0 时会清除自己的投票。
• transition_change：更改变更状态：submit、abandon、restore、wip 或 ready，并可附带消息（submit 不接受消息）。Gerrit 拒绝操作时（例如提交受阻、恢复已合并的变更），会原样报告拒绝原因。

Review 通知

一个可选启用的评审活动推送通道。Agent 使用 subscribe_change 订阅某个更改；此后，新的更改消息、投票、行内评论线程和状态变更都会自动以 review_activity 块的形式出现在会话中。负载使用与读取工具相同的 llmxml 词汇，并包含完整活动，因此之后无需再获取任何内容。unsubscribe_change 可提前结束订阅。已合并或已放弃的更改会通过一条说明情况的最终通知结束自身的订阅；变得无法读取的更改（已删除，或该账号不再可见）也会如此，并明确说明原因。

订阅按会话划分并保存在内存中：不会在 Gerrit 实例上留下痕迹，会随会话结束；服务器重启后，Agent 需要重新订阅。功能关闭时（默认状态），服务器与启用此功能前完全一致，不会增加任何工具或能力，也不会进行后台轮询。

启用此功能需要配置两端：

1. 服务器端：传入 --review-notifications=true（或对应的环境变量）。服务器会注册两个订阅工具，并每隔 --review-notifications-poll-interval（默认 60s）轮询 Gerrit：每个轮询周期对所有已订阅的更改执行一次批量查询，仅对实际发生变化的更改获取详情。
2. 客户端：事件投递使用 Claude Code channels 合约（研究预览版，Claude Code 2.1.80 或更高版本）。对于直接在 mcpServers 下注册的服务器，使用 claude --dangerously-load-development-channels server:<name> 启动，其中 <name> 是注册键；它会成为注入的 <channel> 块的 source 属性。允许列表中的 channel 插件则使用 claude --channels 加载。

研究预览版注意事项：组织策略可以完全禁用 channels；标志语法可能会随 Claude Code 版本更新而改变；不支持 channel 的客户端会静默丢弃事件，此时服务器的行为与关闭该功能时完全相同，客户端和服务器均不会报错。

噪声控制由运维人员配置。服务器不会自行应用任何启发式规则，也不会按消息标签进行过滤，因为机器人的判定结果往往正是 Agent 正在等待的结果：

• 默认跳过经过身份验证的账号自身的活动（--review-notifications-include-own 会保留这些活动）；
• --review-notifications-exclude-accounts 会屏蔽指定用户名或数字 ID 的账号；
• --review-notifications-exclude-patterns 会丢弃消息或评论文本匹配正则表达式的事件；无效模式会导致启动失败，并显示包含该模式名称的错误。

每个标志都有对应的 GERRIT_MCP_* 环境变量，并遵循其余配置相同的分层设置方式（参见Claude Code 中的项目级配置），因此项目可以在自己的设置文件中启用通知并选择排除项。

配置参考

行为通过 CLI 标志进行配置，每个标志都有对应的环境变量，因此二进制文件和 Docker 调用都可以使用相同的配置方式。优先级：标志优先于对应环境变量，环境变量优先于默认值。

标志	对应环境变量	默认值	含义
--groups	GERRIT_MCP_GROUPS	read	以逗号分隔的功能组：read、comment、transition
--projects	GERRIT_MCP_PROJECTS	（空）	项目允许列表，用于限制所有操作，包括读取操作
--own-changes-only	GERRIT_MCP_OWN_CHANGES_ONLY	true	拒绝对非当前认证账号所有的变更执行可能留下痕迹的操作
--include-tools	GERRIT_MCP_INCLUDE_TOOLS	（空）	仅保留按组解析出的工具集合中列出的工具
--exclude-tools	GERRIT_MCP_EXCLUDE_TOOLS	（空）	从按组解析出的工具集合中移除列出的工具
--review-notifications	GERRIT_MCP_REVIEW_NOTIFICATIONS	false	启用评审通知
--review-notifications-poll-interval	GERRIT_MCP_REVIEW_NOTIFICATIONS_POLL_INTERVAL	60s	订阅变更的轮询间隔，格式为 Go 时长
--review-notifications-include-own	GERRIT_MCP_REVIEW_NOTIFICATIONS_INCLUDE_OWN	false	在通知中保留当前认证账号自己的活动
--review-notifications-exclude-accounts	GERRIT_MCP_REVIEW_NOTIFICATIONS_EXCLUDE_ACCOUNTS	（空）	其活动永远不会生成通知的账号（用户名或数字 ID）
--review-notifications-exclude-patterns	GERRIT_MCP_REVIEW_NOTIFICATIONS_EXCLUDE_PATTERNS	（空）	以逗号分隔的正则表达式；匹配的消息或评论文本永远不会生成通知

说明：

• --own-changes-only 必须显式指定布尔值：--own-changes-only=false。不带值的标志会导致配置错误。
• 项目范围限制（--projects）由服务端强制执行：无论 Agent 组合了什么查询，都会向每个变更查询注入项目条件，并拒绝对范围外变更执行直接操作。
• 工具筛选器只会缩小范围。--exclude-tools 会从已解析的工具组中移除工具；--include-tools 只保留其中列出的子集。筛选器无法启用未包含在已启用工具组中的工具，且排除规则优先于包含规则。筛选条目若指向未知工具，会导致启动失败，以便立即发现配置错误。
• 配置错误会汇总处理：服务会一次性报告所有问题，然后以非零状态退出。

输出格式

每个工具都以 llmxml 格式响应。这是一种便于大模型处理的 XML 子集：按行组织、带有语义标签，旨在供模型读取。属性承载元数据，元素主体承载内容：

<changes query="status:open owner:self" start="0" count="1" more="false">
<change number="12345" project="core" branch="main" status="NEW" owner="Jane Doe (jdoe)" updated="2026-07-10T20:48:32Z">fix scanner initialization</change>
</changes>

该格式没有 XML 声明、命名空间或架构，也不会被解析回其他形式。如果需要机器可读的 Gerrit 数据，请直接使用 Gerrit 的 REST API；此格式用于模型读取。

许可证

MIT