GitHub MCP Server

AI 代理的完整 GitHub 集成

将 AI 代理连接至 GitHub，实现仓库管理、代码操作、问题追踪、拉取请求及完整的 GitHub API 功能。

为什么选择 GitHub MCP？

🤖 代理原生的 GitHub 工作流

使代理能够执行以往需手动编写 API 调用才能完成的复杂 GitHub 操作：

• 克隆并导航仓库
• 读取和修改文件
• 创建问题和拉取请求
• 审查代码与讨论
• 管理分支和发布版本

🔐 安全的身份验证

基于 OAuth 的身份验证机制，支持细粒度权限控制。代理仅能访问您授权的内容。

📦 常见操作零配置

预配置了最常用的 GitHub 工作流工具，无需手动调用 API。

安装

选项 1：官方 MCP 服务器（已归档 - 社区维护）

# 社区维护的 GitHub MCP 服务器
npm install -g @modelcontextprotocol/server-github

# 或从源码构建
git clone https://github.com/modelcontextprotocol/servers-archived
cd servers-archived/src/github
npm install
npm run build

选项 2：第三方实现

多个社区实现可用。请在 [MCP 注册表](https://registry.modelcontextprotocol.io/) 中查看当前可用选项。

配置

将以下内容添加至您的 MCP 客户端配置中：

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

获取 GitHub Token

1. 访问 https://github.com/settings/tokens
2. 生成新令牌（经典令牌）或细粒度令牌
3. 选择作用范围：

- repo - 完全访问仓库

- read:user - 读取用户资料

- read:org - 读取组织数据（如需访问组织仓库）

细粒度令牌（推荐）：

• 仓库权限：内容（读/写）、问题（读/写）、拉取请求（读/写）
• 组织权限：成员（读），如需访问组织仓库

可用工具

仓库操作

1. 创建仓库

Agent: "创建一个名为 'my-project' 的新仓库"

2. 克隆仓库

Agent: "克隆 OpenAI GPT-4 仓库"

3. 列出仓库文件

Agent: "src/ 目录中有哪些文件？"

文件操作

4. 读取文件

Agent: "显示 README.md 文件内容"
Agent: "读取 src/index.ts 的内容"

5. 创建/更新文件

Agent: "创建新文件 docs/API.md 并添加 API 文档"
Agent: "将 package.json 中的版本更新为 2.0.0"

6. 搜索代码

Agent: "搜索包含 '认证逻辑' 的文件"
Agent: "查找 DatabaseConnection 类的定义位置"

问题与拉取请求管理

7. 创建问题

Agent: "创建一个问题：'添加暗色模式支持'"

8. 列出问题

Agent: "显示所有未解决的错误"
Agent: "哪些问题分配给我了？"

9. 创建拉取请求

Agent: "创建一个将 feature/login 合并到 main 分支的 PR"

10. 审查拉取请求

Agent: "审查 PR #42，检查是否存在安全问题"

分支操作

11. 创建分支

Agent: "创建一个名为 'feature/user-auth' 的新分支"

12. 列出分支

Agent: "显示此仓库中的所有分支"

13. 合并分支

Agent: "将 develop 分支合并到 main"

高级操作

14. 创建发布版本

Agent: "创建 v2.0.0 版本的发布，包含最新更改"

15. 搜索仓库

Agent: "查找流行的 React 组件库"

16. fork 仓库

Agent: "将 Vue.js 仓库 fork 到我的账户下"

代理工作流示例

代码审查自动化

Human: "审查所有拉取请求并标记安全问题"

Agent:
1. list_pull_requests(state="open")
2. 对每个拉取请求：
   - get_pull_request(pr_number)
   - read_changed_files()
   - 分析是否存在安全漏洞
   - create_review_comment(security_findings)

问题分类处理

Human: "将所有新问题标记为 'needs-triage'"

Agent:
1. list_issues(state="open", labels=null)
2. 对每个未标记的问题：
   - read_issue(issue_number)
   - add_label("needs-triage")

发布自动化

Human: "准备 v2.0.0 版本发布"

Agent:
1. create_branch("release/v2.0.0")
2. update_file("package.json", version="2.0.0")
3. update_file("CHANGELOG.md", new_release_notes)
4. create_pull_request("release/v2.0.0" -> "main")
5. create_release(tag="v2.0.0", notes=changelog)

文档同步

Human: "根据代码注释更新文档"

Agent:
1. search_code(query="* @description")
2. 提取文档字符串
3. 生成 Markdown 文档
4. 更新文件 "docs/API.md" 内容
5. 创建拉取请求："更新 API 文档"

使用场景

🛠️ 开发助手

帮助开发者完成重复性的 GitHub 操作：创建问题、管理标签、更新文档、代码审查。

🤖 CI/CD 自动化

构建可触发工作流、检查构建状态、创建发布版本、管理部署的代理。

📊 仓库分析

分析代码质量、跟踪问题解决时间、监控拉取请求速度、生成报告。

🔍 代码搜索与发现

查找代码模式、识别依赖项、发现相似实现、定位技术债务。

📝 文档自动化

将代码注释同步至文档、生成 API 参考、更新变更日志、维护 README 文件。

安全最佳实践

✅ 使用细粒度令牌

优先使用细粒度令牌而非经典个人访问令牌（PAT）。限制作用范围至特定仓库和权限。

✅ 尽可能使用只读权限

若代理仅需读取代码或问题，请授予只读访问权限。

✅ 使用环境变量

切勿在代码中硬编码令牌。始终通过环境变量传递。

✅ Token 轮换

定期轮换令牌，并设置过期时间。

✅ 审计代理操作

监控代理的执行行为。GitHub 活动日志可追踪所有 API 操作。

速率限制

已认证请求：

• 5,000 次/小时（每用户）
• 搜索 API：30 次/分钟

最佳实践：

• 尽可能缓存仓库数据
• 在适用情况下批量处理操作
• 使用条件请求（If-None-Match 请求头）

与手动 GitHub API 集成对比

故障排查

“凭证无效”错误

• 确认令牌未过期
• 确保令牌具有必要作用域（如 repo、read:user）
• 检查环境变量中是否正确设置了令牌

“资源未找到”错误

• 确认仓库名称格式为：owner/repo
• 检查代理是否有权限访问私有仓库（如适用）
• 确保分支或文件路径存在

速率限制错误

• 等待速率限制重置（检查 X-RateLimit-Reset 响应头）
• 降低请求频率
• 考虑使用 GitHub Apps 以获取更高限额

资源

• MCP 注册表: https://registry.modelcontextprotocol.io/
• GitHub API 文档: https://docs.github.com/en/rest
• 创建个人访问令牌: https://github.com/settings/tokens
• 速率限制说明: https://docs.github.com/en/rest/overview/rate-limits-for-the-rest-api

高级配置

{
  "mcpServers": {
    "github": {
      "command": "node",
      "args": ["/path/to/github-mcp/build/index.js"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx",
        "GITHUB_API_URL": "https://api.github.com",
        "DEFAULT_BRANCH": "main",
        "AUTO_PAGINATION": "true"
      }
    }
  }
}

每个编码代理都不可或缺的 GitHub 集成：从代码审查到发布自动化，GitHub MCP 为 AI 代理带来 GitHub 的全部能力。