GitHub MCP Server 接入指南

mcp-server-github 快速入门

让 Claude Code / OpenCode 直接”接上” GitHub,AI 能自己读 Issue、改 PR、查代码,不用你贴 URL。

这是什么?解决什么问题?

用 AI 编程助手时,最常见的工作流是:复制 GitHub Issue URL → 贴给 AI → AI 写代码 → 你再去 GitHub 创建 PR。这套流程割裂、容易丢上下文。 @modelcontextprotocol/server-github 是 Model Context Protocol 官方组织维护的 GitHub MCP Server。它跑在你的本地,通过 MCP 协议把 GitHub 的能力”暴露”给 AI:

• 读 Issue / PR / Discussion
• 创建 PR、写评论、合并 PR
• 搜索仓库代码
• 读 / 写仓库文件
• 触发 Workflow
• 看 Repo Insights(Stars、Traffic、Contributors) AI 拿到这些工具后,不需要你贴 URL,它能直接通过 MCP 调 GitHub API 完成所有动作。MCP 和 Skill 不冲突:Skill 给 AI”知识/规则”,MCP 给 AI”工具/能力”,两者叠加才是完整的”AI 程序员”。 适合:重度 GitHub 协作的开源维护者、企业内部用 GitHub 的研发团队、独立开发者。

准备工作

• Node.js ≥ 18
• 一个 GitHub 账号
• 一个 GitHub Personal Access Token(PAT),需要在 developer settings 里生成,勾上 repo、workflow、read:org(按需)
• Claude Code 或 OpenCode(支持 MCP 协议)
• 5 分钟

3 步快速上手

第 1 步:配置 MCP Server

在 Claude Code 里,执行:

/mcp add github -- npx -y @modelcontextprotocol/server-github

或者手动编辑 ~/.claude/mcp.json(或对应工具的配置文件):

{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxxxxxxx"
}
}
}
}

注意:Token 存进 env 而不是 args,更安全。.mcp.json 也要 chmod 600,避免被同机器其他用户读到。

第 2 步:验证 MCP 工具列表

重启客户端,跑:

/mcp list

看到 github Server,且下面列出 create_issue、create_pull_request、search_code、get_file_contents 等 20+ 工具,即说明连接成功。 可以做一个 smoke test:

用 github MCP 列出我的仓库 octocat/Hello-World 的最近 3 个 issue。

第 3 步:用 MCP 跑第一个真实任务

在 agent 对话里说:

用 github MCP 给我读 issue #123,把里面的需求实现并提交 PR。

观察 AI 行为:

• 自动调 get_issue 拿到 issue 内容;
• 自动调 list_branches 找到 main 分支;
• 自动 create_branch 开新分支;
• 自动改文件、调 create_or_update_file 写代码;
• 自动 create_pull_request 创建 PR,标题里自动 @ 提及 issue 编号(如 “Fix #123”);
• 整个过程你不需要复制粘贴任何 URL。

常见踩坑

1. PAT 权限不够:Token 没勾 repo 就只能读公开 repo,操作私有 repo 会 403。回 developer settings 加权限。
2. Token 泄露到聊天记录:不要把 Token 直接贴 prompt 里,放 .mcp.json 的 env 字段;如果已经泄露,立即 revoke 重新生成。
3. MCP Server 启动失败:Node 版本太低(< 18)会跑不起来,node -v 验证一下。
4. 协议版本不匹配:MCP 协议还在演进,部分老版本 client 不支持新 Server,出错信息里会有 “protocol version mismatch”,升级 client。
5. AI 滥用写权限:MCP 给了”创建 PR”能力,AI 可能在你没注意时直接 push 代码。生产 repo 建议用 read-only Token 跑 MCP,真要写再用更高权限。
6. Rate Limit 撞墙:GitHub API 每小时 5000 次请求,频繁操作(批量给 100 个 issue 加 label)会触发,需要降速或用 App Token 提升额度。

初级用法

• 看 PR 不打开网页:在 IDE 里直接 列出 PR #45 的所有 review comments,节省切换窗口。
• 批量管理 issue:把”按 label 关闭 30 天未更新的 issue”这种活交给 AI 跑。

高级玩法

• CI/CD 集成:让 MCP 触发 GitHub Actions,比如”PR 合并后自动部署到 staging”。
• 多 Server 串联:把 github、gitlab、linear、notion 四个 MCP Server 一起接,AI 可以在 GitHub 改 PR → 在 Linear 改 ticket 状态 → 在 Notion 更新文档,端到端。
• 企业级权限:用 GitHub App 而不是 PAT,可以做到”按仓库授权”,避免给 AI 整个 org 的权限。

小技巧

• repo scope 太大时,先开 public_repo + read:user 跑通最小链路,再按需扩。
• 用 gh auth token 直接拿到本机 gh 工具的 Token,作为 GITHUB_PERSONAL_ACCESS_TOKEN,省事且自动续期。
• 给 MCP 操作加”二次确认”配置:Claude Code 里 --permission-mode acceptEdits 只允许编辑,不允许跑命令,更稳。
• MCP 工具的 prompt 可以精简:很多工具会消耗上下文,让 AI 只列”我当前用到的工具”即可。
• 定期 gh auth refresh 更新 Token,避免 90 天过期。

参考链接

• MCP 官方仓库
• GitHub MCP Server 目录
• MCP 协议规范
• GitHub PAT 申请
• Claude Code MCP 文档
• 相关 Skill:tdd、diagnose、grill-me