Quartz 4

🔍 搜索

Gerrit MCP Server 使用指南（网关版）

10 min read

Gerrit MCP Server 使用指南_网关版

简介

该项目从上游谷歌官方项目 gerrit-mcp-server 二次开发修改而来，修复了原项目的一些缺陷，重构了部分代码，增强了扩展性和稳定性。

核心优势

🚀 零依赖部署

本地无需安装其他环境或服务，只需配置 MCP 统一网关的转发地址即可使用

🌐 多域名支持

支持配置多个 Gerrit 域名，灵活切换不同环境，提升工作效率

🔒 权限控制

读写权限分离，默认只读模式，降低误操作风险，保障代码安全

💡 典型使用场景

  • 查询 6977312 这个 change 的详情（从默认域名查询）
  • 查询 https://gerrit.odm.mioffice.cn/ 域名下的 1153597 change 详情
  • 支持 @resources/host-aliases 添加上下文，直接查询：“查询 odm 下的 change 1153597 详情”

快速开始

📋 前置条件

  • 拥有 Gerrit 账号并可正常登录
  • 网络可访问公司内网（MCP 统一网关地址）
  • 已安装支持 MCP 协议的 AI 客户端（如 ClaudeCode、Kiro 等）

第一步：获取访问凭证

  1. 访问 MCP 统一网关（https://onedev.pt.miui.com/gateway/tokens）
  2. 【使用管理】-【Token管理】创建token，绑定Gerrit MCP服务

或者已有 Token，绑定 Gerrit MCP 服务。

  1. 复制MCP配置到个人的MCP Client里

第二步：最简配置

在 AI 客户端的 settings.json 中添加以下配置（可从管理平台【MCP 配置】里复制，如上）：

{
  "mcpServers": {
    "gerrit_mcp": {
      "httpUrl": "https://onedev.pt.miui.com/mcp-gw/gerrit_mcp",
      "timeout": 15000,
      "headers": {
        "x-user-token": "mcp_u-your-token-here",
        "x-gerrit-default": "pt",
        "x-gerrit-host-pt": "https://gerrit.pt.mioffice.cn/",
        "x-gerrit-host-odm": "https://gerrit.odm.mioffice.cn/"
      }
    }
  }
}

第三步：验证连接

重启 AI 客户端后，尝试执行：

查询XX最近的 change list

如果返回结果，说明配置成功！

详细配置

MCP客户端详细配置

在 MCP 管理平台配置 Gerrit 服务器信息：

{
  "mcpServers": {
    "gerrit_mcp": {
      "httpUrl": "https://onedev.pt.miui.com/mcp-gw/gerrit_mcp",
      "timeout": 15000,
      "headers": {
        "x-user-token": "mcp_u-your-token-here",
        "x-permission-mode": "r",
        "x-gerrit-default": "pt",
        "x-gerrit-host-pt": "https://gerrit.pt.mioffice.cn/",
        "x-gerrit-host-odm": "https://gerrit.odm.mioffice.cn/",
        "x-gerrit-host-xring": "http://gerrit.x-ringtek1.srv/",
        "x-gerrit-auth-xring": "your_username|your_password"
      }
    }
  }
}

MCP 客户端配置

| 参数 | 类型 | 必填 | 说明 | httpUrl / url | String | ✅ | MCP 统一网关转发服务地址（生产环境或预发环境） | timeout | Integer | 推荐 | 请求超时时间（毫秒），推荐 15000-30000 | headers.x-user-token | String | ✅ | MCP 统一网关平台分配的用户认证 token | headers.x-permission-mode | String | 非必填 | 权限模式：r（只读）/ w（只写）/ rw（读写），默认 r | headers.x-gerrit-default | String | ✅ | 必须要指定一个 host 的别名，在调用具体 MCP 工具时可以不填写具体的域名 | headers.x-gerrit-host-pt headers.x-gerrit-host-odm | String | 非必填 | pt 和 odm 的认证已经和 MCP 统一网关打通了，不需要填写 auth 信息，默认使用的就是登陆MCP 统一网关的username，其他平台需要填写 | headers.x-gerrit-host-XX headers.x-gerrit-auth-XX | String | 非必填 | 其他域名需要填写 host 地址和 auth 认证，auth 信息的 username 和 password 使用竖线 | 分隔 密码获取方式，如下：- 登录 Gerrit 首页

  • 进入 Settings > HTTP Credentials image.png

🎁 注意：如果在其他业务里已经填过了 password，不需要重新生成，直接复制过来使用，重新生成会导致之前的失效。

权限模式详解

r - 只读模式（推荐）

可用工具：

  • 查询 changes
  • 获取详情
  • 查看 diff
  • 读取评论 **适用场景：**日常查询、代码审查、问题排查

w - 只写模式

可用工具：

  • 添加 reviewer
  • 设置状态
  • 发布评论
  • 创建 change **适用场景：**自动化操作、批量处理

rw - 读写模式

可用工具：

  • 全部工具 **适用场景：**高级用户、完整工作流

🎁 权限模式安全提示使用 w 或 rw 权限时，存在以下风险：

  • AI 模型可能因上下文遗忘执行错误操作
  • 模型幻觉可能导致误 revert 或 abandon change
  • 建议仅在必要时临时开启写权限，操作完成后立即切换回只读模式

支持的工具列表

查询类工具（只读权限）

工具名称功能说明风险等级
query_changes根据查询字符串搜索 CLs🟢 低
query_changes_by_date_and_filters按日期范围和过滤条件搜索 changes🟢 低
get_change_details获取单个 CL 的完整详情🟢 低
get_commit_message获取当前 patch set 的 commit message🟢 低
list_change_files列出最新 patch set 中修改的所有文件🟢 低
get_file_diff获取 CL 中指定文件的 diff🟢 低
list_change_comments获取 change 的所有评论🟢 低
get_most_recent_cl获取用户最近的 CL🟢 低
get_issues_from_cl从 commit message 提取 JIRA/ADT issue ID🟢 低
changes_submitted_together列出会一起提交的所有 changes🟢 低
get_related_changes获取相关的 changes（依赖关系）🟢 低
suggest_reviewers根据查询建议 reviewers🟢 低
get_blame_from_diff追踪代码行的 commit 历史🟢 低
list_draft_comments列出 CL 上当前用户的所有草稿评论🟢 低

操作类工具（写权限）

工具名称功能说明风险等级
add_reviewer添加 reviewer 或 CC🟡 中
set_ready_for_review设置 CL 为 ready for review🟡 中
set_work_in_progress设置 CL 为 work-in-progress🟡 中
post_review_comment在文件特定行发布评论🟡 中
set_topic设置或删除 change 的 topic🟡 中
create_change创建新的 change🟡 中
abandon_change废弃 change🔴 高
revert_change回滚单个 change🔴 高
revert_submission回滚整个 submission🔴 高
post_draft_comment创建草稿评论（支持行范围、代码建议、线程回复）🟡 中
delete_draft_comment删除单条草稿评论🟡 中
delete_draft_comments删除 CL 上所有草稿评论🟡 中
publish_drafts发布所有待处理草稿评论（等同于 Gerrit 网页的 “Send”）🟡 中

使用示例

场景 1：查询和分析

# 查询xx最近的 CL
查询xx最近提交的 change
 
# 查看特定 CL 的详情
查询 change 6977312 的详情
 
# 查看文件修改
列出 change 6977312 修改了哪些文件
 
# 查看具体 diff
显示 change 6977312 中 main.py 的 diff

场景 2：跨域名查询

# 查询 ODM 环境的 change
查询 https://gerrit.odm.mioffice.cn/ 下的 change 1153597
 
# 使用别名（需添加 host-aliases 作为上下文）
查询 odm 下的 change 1153597 详情

场景 3：代码审查（需写权限）

# 添加 reviewer
给 change 6977312 添加 reviewer lisi@example.com
 
# 发布评论
在 change 6977312 的 main.py 第 42 行添加评论："建议优化这里的逻辑"
 
# 设置状态
将 change 6977312 设置为 ready for review

安全最佳实践

UserToken 管理

🔐 重要安全提示

  1. 不要将 token 提交到代码仓库
  2. 发现泄露立即在平台删除并重新生成

权限使用建议

  1. 默认使用只读模式：日常查询和分析使用 r 权限
  2. 临时开启写权限：需要操作时临时修改为 w 或 rw，完成后立即切换回 r
  3. 避免长期开启 rw：降低误操作风险
  4. 重要操作前确认：执行 revert、abandon 等操作前，先用只读模式确认信息

故障排查

常见问题

1. 连接超时

症状： 请求一直等待，最终超时解决方案：

  • 检查 httpUrl 是否正确
  • 增加 timeout 值（如 30000）
  • 确认网络可以访问 MCP 服务地址

2. 认证失败

症状： 返回 401 或 403 错误解决方案：

  • 验证 x-user-token 是否正确
  • 检查 token 是否过期
  • 确认 Gerrit auth_token 是否有效

3. 工具列表为空

症状： AI 提示没有可用的 Gerrit 工具解决方案：

  • 检查 x-permission-mode 配置
  • 重启 AI 客户端
  • 查看客户端日志确认 MCP 连接状态

4. 多域名切换失败

症状： 无法查询非默认域名的 change解决方案：

  • 确认 MCP 平台已配置多个 host
  • 使用完整 URL 指定域名
  • 检查目标域名的 auth_token 是否正确

环境地址

环境MCP统一网关用途
预发环境https://onedev-preview.pt.miui.com/gateway/tokens验证
生产环境https://onedev.pt.miui.com/gateway/tokens正式使用

技术支持

如遇到问题，请联系：

  • 技术支持群：（待补充）
  • 问题反馈：（待补充）
  • 文档更新：（待补充）

最后更新：2026-03-13

Graph View