【Hermes：MCP 与工具实战】28、GitHub MCP 深度实战：PR 审查、Issue、自动汇报全搞定

GitHub MCP 深度实战：PR 审查、Issue、自动汇报全搞定

从 Token 申请到自动化运维，手把手教你让 Hermes 变成 7×24 小时的 GitHub 管家

前言：为什么你的 AI Agent 需要一个 GitHub MCP？

如果你还在用手动方式切到 GitHub 网页上合并 PR、回复 Issue、盯每日项目进展，你的开发效率已经落后了。

Hermes Agent 的爆发式增长到 2026 年 4 月已经突破了 10.5 万 GitHub Star。其背后一个极其强大却又容易被忽略的能力，就是它通过 MCP（模型上下文协议） 无缝接入 GitHub，让开发者可以直接用 自然语言 驱动机器人完成从代码审查到 Bug 追踪的几乎所有日常工作。

具体来说，本文涉及的能力包括：

• GitHub Token 的申请与权限分配（这是安全基础，必须做对）
• config.yaml 配置 GitHub MCP
• 自然语言直接操作 GitHub（仓库、Issue、PR 等）
• 自动 PR 审查 Skill 配置
• 定时汇报：结合 Cron 与 GitHub MCP 做项目日报
• per-server 工具过滤：实现最小权限原则
• 常见问题与排障

套用一句话总结本文流程：你只需对 AI"口述"命令，AI 就去操作 GitHub。整个过程可自动化、定时化、技能化。

一、GitHub Token 申请与权限配置（基础篇）

要在 Hermes 里唤醒 GitHub MCP，核心就是要有一个 GitHub Token。

1.1 为什么要用 Fine-Grained Token？

早期很多人都喜欢图省事直接用 Classic PAT。但这种方式权限很粗，往往一给就是一堆仓库的全部读写权限------一旦 Token 泄露，攻击者能造成较大损失。

从 2026 年的安全实践看，GitHub 官方推荐使用 Fine-Grained Personal Access Tokens。这种 Token 允许设置到"具体哪一个仓库（甚至是某一个具体的代码库）、哪一类 API 权限"，严格遵守"最小权限"原则。

1.2 Fine-Grained Token 申请步骤

在浏览器中按以下顺序找到申请入口：
图例说明
备注：建议仅授权必要权限，遵循'最小权限'原则
GitHub 右上角头像
Settings
Developer settings
Personal access tokens
Fine-grained tokens
按钮：Generate new token
填写 Token 信息
Token name: HERMES-MCP
Expiration: 根据安全策略设置
Repository access: 选 All or Select
设置 Permissions
Contents: Read & write
Pull requests: Read & write
Issues: Read & write
Metadata: Read
Workflows: Read & write 可选
Actions: Read & write 可选
点击 Generate token
复制生成的 Token
Token 生成完成，妥善保存

最小权限清单：

• Contents（仓库内容） ：建议 Read & write（用于读取代码、创建/修改文件）
• Pull requests ：Read & write（用于创建/审查 PR）
• Issues ：Read & write（用于创建/回复 Issue）
• Metadata ：Read
• Workflows ：Read & write 或 Read（如果要实现 CI 自动化则需要写权限）
• Actions ：如果要做 Action 日志监控，需要 Read & write。

务必点击 Generate token 后立即把 Token 复制出来。一旦刷新界面就不可见。

官方关键信息：Fine-Grained PAT 是经典 PAT 的更细化且安全替代方案，允许用户定义高度具体的访问权限来访问仓库、组织或其他资源。

二、config.yaml 配置 GitHub MCP（接入实操）

Hermes 的 MCP 配置非常简单直观。它支持通过 mcp_servers 字段接入几乎任何一种外部 MCP Server，包括 GitHub。GitHub 官方也提供了对应的 MCP Server，专用于将仓库、Issue、PR、Actions 等能力暴露给支持 MCP 的 Agent。

2.1 确定安装路线

路线 A（官方 MCP Server） ：直接使用 GitHub 官方提供的 @modelcontextprotocol/server-github 官方 MCP Server。

路线 B（自定义对接） ：如果已经配置了 gh CLI 环境，也可以直接用 gh 驱动自定义工具（部分场景可能路径更短）。

2.2 准备 MCP Server 插件

如果选择路线 A，在你安装了 Node.js 和 npm 的机器上，不必手动执行这条命令（它会在 Hermes 配置中被动态拉取），但你也可以提前本地安装确保环境没问题：

npm install -g @modelcontextprotocol/server-github
# 或全局使用 npx（更推荐无全局安装）

不过 Hermes 配置 MCP 时，通常是在启动 Hermes 时自动通过 npx 去下载运行的。

2.3 修改 ~/.hermes/config.yaml

找到 ~/.hermes/config.yaml，在文件末尾或合适位置添加如下 MCP 服务器配置：

mcp_servers:
  # Composio MCP 示例（如需要接入1000+第三方工具时使用）
  composio:
    url: "https://connect.composio.dev/mcp"
    headers:
      x-consumer-api-key: "YOUR_COMPOSIO_API_KEY"
    connect_timeout: 60
    timeout: 180
  
  # GitHub Official MCP Server（核心配置）
  github:
    # 方案一：通过 Command 模式（推荐，轻量）
    command: "npx"
    args:
      - "-y"
      - "@modelcontextprotocol/server-github"
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "your_fine_grained_github_token_here"
      GITHUB_READ_ONLY: "false"      # true 时变为只读模式，无法创建 PR/Issue 等
      # GITHUB_LOCKDOWN_MODE: "false" # 如需限制公共仓库访问外部贡献者，设为true

    # 方案二（备选）：如果偏好 http 模式且有相关服务端
    # url: "http://localhost:3000/mcp"
    # headers:
    #   Authorization: "Bearer your_token"

重要提示 ：不要把 Token 直接硬编码写死在 config.yaml 中，而是应该将 GITHUB_PERSONAL_ACCESS_TOKEN 放在 ~/.hermes/.env 中，然后通过环境变量引用。

更好的写法是在 ~/.hermes/.env 中添加：

# ~/.hermes/.env
GITHUB_PERSONAL_ACCESS_TOKEN=github_pat_your_fine_grained_token_here

然后在 config.yaml 的 github 部分的 env 字段直接引用。

2.4 工具注入机制

配置 GitHub MCP 后，Hermes 会自动完成三件事：

• 建立与 MCP 服务器的连接
• 动态发现可用的 GitHub 相关工具
• 将这些工具注册到 Agent 的可用工具集中

这使得 Agent 无需额外配置就能直接调用 GitHub 操作工具。

2.5 安全模式选择

GitHub MCP 官方支持两种安全隔离模式：

模式	开启方式	作用
Read-Only Mode	env: GITHUB_READ_ONLY: "true"	移除所有具有写入操作的工具（如创建 PR、添加 Issue 评论、修改文件等），适合仅查看项目的场景
Lockdown Mode	env: GITHUB_LOCKDOWN_MODE: "true"	限制对公共仓库中外部贡献者内容的访问，仅允许访问具有推送权限的作者的内容

三、自然语言操作 GitHub（仓库、Issue、PR）

这是日常使用最频繁的场景。一旦 MCP 配置好，你就可以在 Hermes CLI 或 Gateway 中直接对 AI 下指令了。

3.1 仓库操作示例

自然语言指令	执行效果
"列出 Hermes Agent 仓库里最近更新的一些 issue"	调用 list_issues 工具
"搜索 label:bug 的 issue"	根据标签过滤
"查看我的仓库 my-project 的拉取请求"	列出所有 PR 状态

3.2 Issue 操作示例

# 查看指定 Issue 详情
hermes
> 查看 https://github.com/NousResearch/hermes-agent/issues/188 的详情

Agent 会直接输出该 Issue 的标题、状态、标签、对话历史截图（文字模拟）。

# 创建新 Issue
> 在我的仓库 test/demo 创建一个 Issue，标题是"CI 流水线超时"，内容描述最近构建失败两次

（由于有写入权限）很快 Agent 会返回 Issue 创建成功的 URL 和编号。

3.3 自动 PR 全流程

下面这张流程图展示了一次完整的"自然语言驱动 PR"全链路：
GitHub MCP Server
用户: 帮我针对 main 分支

创建一个 PR，标题优化文档
Hermes Agent
调用 GitHub MCP 工具
create_branch

从 main 切出 fix/docs
create_or_update_file

在 fix/docs 中修改 README.md
create_pull_request

将 fix/docs 合并到 main
返回结果
用户: PR 已创建

ID: #123

关键细节 ：Agent 并非一次完成全部操作，而是在内部决策引擎下按顺序调用三个工具：create_branch → create_or_update_file → create_pull_request。只要配置了对应权限，整个过程会自动完成。

3.4 自然语言操作的"技能化"

每当你通过自然语言完成了一个多步骤任务（例如"创建分支→改动文件→开 PR"调用超过 5 次工具动作），Hermes 会自动沉淀技能 ：自动提取执行路径和参数模板，生成一个名为 github-auto-pr 的 SKILL.md 文件保存在 ~/.hermes/skills/ 目录中。下次类似场景，直接调用技能，不用重复描述。

四、自动 PR 审查 Skill 配置（高效代码质量管控）

这一块是绝大多数技术团队最看重的。Hermes Agent 通过与 GitHub MCP 结合，可以做自动化、深度的 PR 语义审查。

Hermes 官方已内置了 GitHub 代码审查技能，安装即可直接使用，无需从零编写。

4.1 自动 PR 审查流程图

下面这张流程图展示了从 PR 创建到审查结果反馈的完整链路：
输出阶段
Agent 处理阶段
触发阶段
开发者 Push 到 PR 分支
GitHub 触发 webhook 或 cron 扫描
Hermes 监控检测到 新 PR/未审查 PR
调用 GitHub MCP 工具获取变更文件列表
逐文件执行语义级代码审查

覆盖安全、逻辑、风格
生成审查报告

含行号标注 + 修复建议 + 严重性分级
将报告评论发布到 PR 下
标记审查状态
开发者收到通知

可直接在 UI 下回复

4.2 准备环境：安装 GitHub MCP 与 gh CLI

要让 Hermes 自动审查 PR，推荐提前预装好 gh CLI，并让 gh 完成登录（尽管借助 MCP 内部可以绕过，但很多底层命令可能依赖 gh 认证缓存）。

# 安装 GitHub CLI (如尚未安装)
brew install gh          # macOS
# 或 sudo apt install gh  # Ubuntu/Debian

# 登录 GitHub
gh auth login

# 选用 HTTPS/SSH 均可，选择仓库访问范围后一次性确认

如果使用 GitHub MCP 配置了 Token，理论上 "gh 本地登录"不是强制要求（因为 MCP Server 会直接用 token 认证），但从排错角度讲，让 gh 保持登录总没坏处。

4.3 步骤一：安装 GitHub 代码审查技能

执行以下命令安装官方提供的 GitHub 代码审查技能：

hermes skills install github-code-review

验证技能是否安装成功：

hermes skills list | grep "github-code-review"

如果技能未正常安装，检查 gh 认证状态：

gh auth status
# 如未登录，执行 gh auth login 完成 OAuth 认证

4.4 步骤二：对指定 PR 执行自动审查

假设目标仓库为 team/project，PR 号为 #42：

hermes skills run github-code-review --pr=42 --repo=team/project

该命令会完成以下操作：

1. 获取 PR 变更文件列表
2. 推理工具调用链路（比如读取 PR diff）
3. 利用 LLM 做语义级审查（安全漏洞、逻辑缺陷、风格一致性）
4. 输出结构化的审查报告

如需将报告导出为 Markdown 文件：

hermes skills run github-code-review --pr=42 --repo=team/project --output=review-report.md

审查结果 将自动包含以下内容：

• ✅ 带行号标注的问题点
• ✅ 修复建议
• ✅ 严重性分级（High/Medium/Low）

4.5 步骤三：本地代码变更预检（Push 前审查）

在将代码推送到远程仓库之前，可以在本地执行审查，避免问题进入 CI 流水线：

# 确保当前目录为 Git 仓库根路径
cd /path/to/your/repo

# 暂存待审查的变更
git add .

# 触发本地审查
hermes skills run github-code-review --local

审查完成后，Agent 还会提示是否自动创建修正 commit，输入 y 确认，或手动执行 git commit。

4.6 步骤四：配置 CI/CD 自动审查

为了实现每次 PR 触发时自动审查，可以在 .github/workflows/hermes-review.yml 中添加如下配置：

name: Hermes PR Review
on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Install Hermes Agent
        run: |
          curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
          source ~/.bashrc

      - name: Run GitHub code review
        run: |
          hermes skills run github-code-review --pr=${{ github.event.number }} --repo=${{ github.repository }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

审查报告将自动作为 PR 评论发布。

4.7 步骤五：自定义审查规则集

Hermes 的技能模板完全兼容 agentskills.io 开放标准。通过覆盖默认提示模板，可以让审查行为适配项目的特定规范：

# 定位模板文件
ls ~/.hermes/skills/github-code-review/templates/

# 备份原文件
cp default.md default.md.bak

# 编辑 default.md，在"检查项"章节下新增自定义条目
# 例如：- 确保所有导出函数均配有 @returns JSDoc 注释
#      - 禁止在代码中出现 eval() 调用
#      - 限定 React Hook 的使用方式

# 保存后重启 Agent 使变更生效
hermes restart

五、定时汇报：Cron + GitHub MCP（运维与汇报自动化）

想要每天 9 点自动拉 GitHub 数据，生成"团队昨日项目进展报告"的日报，并推送到飞书或企业微信？有了 cron 功能，配合 GitHub MCP 就能做到。

5.1 cron 的基本用法

Hermes 的 cron 支持自然语言或标准 cron 表达式来调度任务。

核心命令速查：

命令	作用
hermes cron add "0 9 * * *" "任务描述"	添加每天 9 点执行的任务
hermes cron list	查看所有定时任务
hermes cron edit <job_id> --prompt "新任务"	修改任务
hermes cron remove <job_id>	删除任务

5.2 结合 GitHub MCP 编排日报

假设你想每天 9:30 发送昨天以来的 Issue & PR 汇总到消息平台（例如飞书需要预配 gateway 渠道），可以这样创建 cron 任务：

hermes cron add "30 9 * * *" "调用 list_issues 和 list_pull_requests 工具，收集最近1天的 issues：状态 open、总览新增数量，以及 PR 合并状态，并将结果格式化为日报推送到飞书 #general"

关键约束：Cron 任务不适合无限循环的常驻心跳，但特别适合"每天总结新闻""每小时检查某页面""定期发送到 Telegram/Discord/Slack 或飞书"这类明确的小任务。

5.3 结合 Skill 做复杂日报

最稳方式不是把整本操作手册塞进 cron prompt，而是先写好一个专门的日报 Skill，然后在 cron 中快速调用：

# 第一步：进入 Hermes，手动走一遍生成日报的流程
# 例如对话：总结我的仓库近24小时的issue、pr和commit情况，生成Markdown格式日报
# Hermes 将流程自动沉淀为 skill：github-daily-report

# 第二步：创建 cron 任务，引用该 skill
hermes cron add "0 10 * * *" "使用 daily-report 技能发日报"

5.4 cron 任务的执行隔离

每一次定时任务被调度时，Hermes 都会启动一个新的独立 Agent 会话。因此：

• 不要依赖它自动继承当前 CLI 会话的上下文（例如当前 USER.md 中的临时偏好）
• 最佳实践：预先将长期任务需要的偏好和配置固化到 MEMORY.md 或 USER.md 中

六、per-server 工具过滤：最小权限实践

当你配置多个 MCP 服务器（甚至对接不同团队成员的 token），安全就成了第一位。

6.1 为什么需要 per-server 工具过滤？

同一个 Agent 可能同时接入：GitHub MCP（完整读写）、Filesystem MCP（读取本地服务器配置）、以及 Slack MCP。为了防止"模糊的 AI 判断"误删除关键数据或越权发人深省的 PR，必须做工具级过滤。

6.2 GitHub MCP 原生支持的三层安全隔离

GitHub MCP Server 自身提供了多层安全架构，这三层机制在前面步骤中已经隐式启用：

层级	开启方式	效果
Read-Only Mode	env: GITHUB_READ_ONLY: "true"	所有写入类工具（create PR、addIssue 等）从工具清单中彻底移除
Lockdown Mode	env: GITHUB_LOCKDOWN_MODE: "true"	限制公共仓库中外部贡献者的内容访问，仅允许作者具有 push 权限的内容

6.3 使用 per-server 限制（配置文件内）

如果某个 MCP 服务器接入后不想让它用某些危险工具，可以结合 per-server 工具过滤。这不是官方固定语法，但在实践中往往通过在 ~/.hermes/config.yaml 中的工具声明或中间层工具集来完成。

mcp_servers:
  github_readonly:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: ${env: GITHUB_READONLY_TOKEN}
      GITHUB_READ_ONLY: "true"                 # 只读模式：无法创建/修改任何内容
      GITHUB_LOCKDOWN_MODE: "false"

  github_full:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: ${env: GITHUB_FULL_TOKEN}
      GITHUB_READ_ONLY: "false"                # 允许写入（例如给领导做 PR 操作）

⚠️ 安全警钟：永远不要混用极高权限 Token 做非受限操作。一定要至少分只读和写入两类。

七、常见问题：授权失败、权限不足、MCP 无效

7.1 "401 Unauthorized" / "Bad credentials"

原因：GitHub Token无效、过期或缺乏权限。

排查步骤：

1. 验证 Token 本身是否有效：

   curl -H "Authorization: Bearer YOUR_TOKEN" https://api.github.com/user

   正常会返回当前用户信息。

2. 检查 ~/.hermes/.env 中的变量名是否与 config.yaml 里 env 字段的 key 完全匹配（大小写敏感）。

3. 确认 Token 类型是否为 Fine-Grained PAT，以及是否授权了必要的仓库访问权限。

7.2 "Resource not accessible by personal access token"

原因：Token 对当前目标仓库（如某个组织下私有仓库）没有权限。

解决方案：

• 在 GitHub "Fine-grained tokens" → 编辑 Token → "Repository access" → 选 All repositories（或勾选该特定仓库）
• 检查权限列表里面是否勾选了 Contents 的 Read and write 和 Pull requests 的 Read and write

7.3 "mcp server not found" 连接报错

原因 ：npx 首次运行拉包时网络不通，或 command 路径不正确。

解决方案：

# 手动测试一下该命令是否可以正常启动（不要求持续运行，能 exit 也行）
npx -y @modelcontextprotocol/server-github

如果卡住或报 command not found，请确保 Node.js (≥v18) 已安装，npm 可以访问外网。

7.4 GitHub 代码审查技能未触发

解决方案：

1. 确认 hermes skills list 中能找到 github-code-review 技能
2. 如果技能存在但触发不理想，检查 --pr 参数和 --repo 参数格式是否正确
3. 确保 gh auth status 返回已登录（技能内部可能调用 gh）

7.5 Cron 任务未按时执行

解决方案：

1. 确认 Hermes Agent 实例保持 长期运行 状态------Cron 调度器随 Agent 进程工作，Agent 停止则 cron 不触发；
2. 使用 hermes cron list 检查任务是否存在且表达式格式正确；
3. 检查消息平台 Home Channel 是否已配置------日报生成后需要知道往哪里发送

八、总结：Hermes + GitHub MCP，你的永久自动化代码管家

通过本文的完整配置与实战，你将实现从 Token 申请到自然语言控制 GitHub，再到 PR 审查自动化、日报定时汇报的全链路能力集成。

核心收益总结：

能力	收获
Fine-Grained Token 应用	安全的 Token 权限模型，最小化泄露影响
MCP 接入 GitHub	无需手敲 git/github 命令，口语化就能完成 CI 操作
PR 审查自动化	代码质量门禁前移，人工 Review 负担显著降低
Cron + GitHub	日报自动生成推动信息透明、减少会议群聊碎片
per-server 过滤	对高危动作加入锁，同时满足技术同学灵活调用

Hermes MCP 让 AI 不再是只能聊天气的"摆件"，而是能够直接切入工单系统、代码仓库、IM 消息流，代替开发者做枯燥的日常重复劳动。你可以把这些自动化能力通过 Skill 固化下来，形成自己团队或个人的"GitHub 自动化助手"。

欢迎在评论区留下你的 GitHub MCP 最佳实践！

📚 延伸阅读

• Hermes Agent GitHub 仓库
• agentskills.io 开放标准规范
• Hermes 三层记忆机制深度剖析（系列前作）
• GitHub MCP Server DeepWiki

---