/ 目录 / 演练场 / GitHub
● 官方 github 🔑 需要你的密钥

GitHub

作者 github · github/github-mcp-server

赋予 Claude 完整的 GitHub 访问权限 — issues、PRs、代码搜索、文件编辑 — 无需离开聊天窗口。

GitHub 官方提供的 MCP server。你通过 GitHub REST 或 GraphQL API 能做的事,你的 AI agent 都能做:分类 issues、审查 PRs、搜索整个组织的代码、起草 commits。支持只读模式,首次运行时推荐使用。

为什么要用

核心特性

实时演示

实际使用效果

github.replay ▶ 就绪
0/0

安装

选择你的客户端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ]
    }
  }
}

打开 Claude Desktop → Settings → Developer → Edit Config。保存后重启应用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ]
    }
  }
}

Cursor 使用与 Claude Desktop 相同的 mcpServers 格式。项目级配置优先于全局。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ]
    }
  }
}

点击 Cline 侧栏中的 MCP Servers 图标,然后选 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ]
    }
  }
}

格式与 Claude Desktop 相同。重启 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "github",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ]
    }
  ]
}

Continue 使用服务器对象数组,而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "github": {
      "command": {
        "path": "docker",
        "args": [
          "run",
          "-i",
          "--rm",
          "-e",
          "GITHUB_PERSONAL_ACCESS_TOKEN",
          "ghcr.io/github/github-mcp-server"
        ]
      }
    }
  }
}

加入 context_servers。Zed 保存后热重载。

claude mcp add github -- docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server

一行命令搞定。用 claude mcp list 验证,claude mcp remove 卸载。

使用场景

实战用法: GitHub

如何找到好的首个 issue 并在一小时内提交修复

👤 寻求轻松完成首个 PR 的开源贡献者 ⏱ ~60 min beginner

何时使用: 你想为一个项目做贡献,但不知从何开始。维护者的 CONTRIBUTING.md 太笼统,没什么帮助。

前置条件
  • 具有 repo:readissues:read 的 GitHub PAT — github.com/settings/tokens — 使用细粒度 token,限制到你要贡献的仓库
  • 同时安装 filesystem MCP — 让 Claude 能本地克隆和读取仓库,从而实际编写修复
步骤
  1. 让 Claude 找出标记为 good first issue 且无评论的 issues,按复杂度排序
    在 modelcontextprotocol/servers 中找出标记为 'good first issue' 且无受托人和零评论的开放 issues。选择看起来最容易修复的那个,并解释原因。✓ 已复制
    → Claude 返回 3-5 个候选项,每个都有一行难度评估
  2. 让 Claude 获取 issue 正文和任何链接代码
    获取 issue #<num> 的完整正文并读取它提到的文件。告诉我需要进行的实际改动。✓ 已复制
    → 具体的 diff 意图,而不仅仅是重述 issue
  3. 使用 filesystem MCP 进行编辑,然后使用 GitHub MCP 起草 PR
    应用改动,编写一个 PR 描述来感谢维护者,用 3 句话解释修复。✓ 已复制
    → PR 打开并返回链接

结果: 一个尊重项目风格、引用该 issue、足够小能当天合并的开放 PR。

注意事项
  • Claude 选择了一个 'good first issue',但实际上已经放了 2 年,因为没人能就修复达成共识 — 添加 最近 90 天内没有来自维护者的新评论 作为过滤条件
  • PR 正文是通用的 AI 话语 — 先让 Claude 模仿项目最后 3 个已合并 PR 的语气
搭配使用: filesystem · git

为你的团队生成周刊 PR 摘要

👤 工程经理、技术负责人 ⏱ ~10 min intermediate

何时使用: 每个周一早上,当你不想点击 40 条 PR 通知时。

前置条件
  • 限制到你团队仓库且具有 pull_requests:read 的 PAT — 使用细粒度 token,永远不要使用经典的 'all repos' token
步骤
  1. 请求上周已合并 PR 及其 diff 大小
    列出在 org/repo 中从上周一到今天合并的所有 PR。包括作者、+/- 行数和一行摘要。✓ 已复制
    → 包含 10-30 行和具体 delta 的表格
  2. 按作者和主题分组
    按领域(auth、payments、frontend、infra...)分组,并标记看起来像回退或热修复的任何项。✓ 已复制
    → 按主题聚类的章节
  3. 起草一份可用于 Slack 的摘要
    现在写一个 Slack 文章总结这一周 — 庆祝大赢家,指出风险改动,提名那些发布它们的人。✓ 已复制
    → 包含 @mentions 和 emoji 的 Markdown,可直接粘贴

结果: 一个你实际上想在周一早上阅读的 5 点摘要。

注意事项
  • 如果你的组织有很多仓库会触发速率限制 — 一次过滤一个仓库,或升级到 GitHub App token(15k req/h vs 5k)
搭配使用: linear · sentry

找出你的代码库中使用已弃用 API 的所有地方

👤 计划迁移的后端工程师 ⏱ ~30 min intermediate

何时使用: 你即将弃用一个内部类/函数,在宣布前需要知道谁在使用它。

前置条件
  • 具有所有组织仓库 repo:read 权限的 PAT — 使用 GitHub App 进行组织范围访问 — 比分别管理每个仓库的 PAT 更容易
步骤
  1. 在整个组织中使用代码搜索
    在我们整个 acme-corp 组织中搜索 LegacyAuth 类的任何使用。按仓库分组返回文件路径。✓ 已复制
    → 仓库和文件列表,包含行号
  2. 对于每个匹配项,获取上下文
    对于每个匹配项,获取使用周围的 5 行并告诉我这是真实调用还是只是注释/导入。✓ 已复制
    → 区分真实调用和噪声的过滤列表
  3. 生成迁移跟踪 issue
    acme-corp/platform 中创建一个标题为 'Migrate off LegacyAuth' 的跟踪 issue,包含每个真实调用点和拥有每个仓库的团队的检查列表。✓ 已复制
    → 创建包含全面检查列表的 issue

结果: 一个你平台团队可以用来推动迁移的唯一真实来源跟踪 issue。

注意事项
  • 代码搜索每个查询有 1000 个结果的上限 — 如果达到限制,按语言或路径缩小范围:LegacyAuth language:python 或按仓库前缀拆分查询
  • GitHub 仅索引默认分支 — 不会找到功能分支中的使用 — 在克隆的仓库上用本地 grep 补充
搭配使用: filesystem

在批准棘手的 PR 之前获取第二意见

👤 面临超出专业领域的 PR 的代码审查者 ⏱ ~15 min intermediate

何时使用: 你是一个触及你不熟悉的代码的 PR 的指定审查者,你不想只是盖章同意。

步骤
  1. 获取 PR diff 和描述
    获取 org/repo 中的 PR #<num> — 给我 diff 和描述。作者声称这是做什么的?✓ 已复制
    → 意图的清晰重述
  2. 要求进行架构读取
    现在查看此 PR 触及的现有文件。更改是否符合现有模式,还是引入了新模式?如果是新的,新模式是否有道理?✓ 已复制
    → 具体的指出,而不是通用赞美
  3. 探查风险
    在这个 diff 中,哪里最有可能在 6 个月后在生产中破裂?具体指出 — 指向那一行。✓ 已复制
    → 具体的行级关注,而不是 'add more tests'

结果: 三个你可以在 PR 上发布的具体、可行的评论 — 使你的审查比匆匆一瞥更有意义。

注意事项
  • Claude 变成了一台是的机器,赞美一切 — 显式问 '这家公司的高级工程师会反对什么?' — 对抗性框架有帮助
搭配使用: filesystem

识别并解决审查中腐烂的 PR

👤 工程负责人、仓库维护者 ⏱ ~20 min beginner

何时使用: 每个 sprint 一次,当你怀疑 PR 正在悄悄老化而没人注意时。

步骤
  1. 列出开放超过 5 天且没有最近活动的 PR
    org/repo 中找出最后更新超过 5 天的开放 PR。对于每个,告诉我作者、指定的审查者和延迟的陈述原因(查看最后评论)。✓ 已复制
    → 每个 PR 有诊断的表格
  2. 对延迟进行分类
    将这些分组为:'waiting on reviewer'、'waiting on author'、'waiting on CI'、'waiting on decision'。具体说明是哪一个。✓ 已复制
    → 4 个类别,每个都有具体的 PR
  3. 起草提醒
    对于 'waiting on reviewer' 分组,为每个起草一个礼貌的提醒评论。如果审查者是同事还是作者的上级,语气不同。✓ 已复制
    → 每个 PR 的评论文本可以粘贴

结果: 一个你可以在 15 分钟内解开的短 PR 列表,每个 PR 都有具体的操作。

注意事项
  • 自动发布评论感觉像垃圾邮件 — 让 Claude 起草评论,但你自己发布 — 保持人在循环中
搭配使用: linear

组合

与其他 MCP 搭配,撬动十倍杠杆

github + sentry

Sentry 表面出现新错误 → GitHub MCP 通过发布标签找到引入它的 commit → 你在一个聊天中起草热修复 PR

Sentry 中有一个新错误 — issue WEB-3a91。找到 main 上哪个 commit 引入了它(交叉引用发布标签),然后起草最小可能的回退 PR。✓ 已复制
github + linear

从 GitHub bug 报告中自动创建具有适当标签和优先级的 Linear issues

对于这周在我们 octocat/api 仓库中打开的每个标记为 'bug' 的 issue,在 BACKEND 团队中创建具有中等优先级的匹配 Linear issue。✓ 已复制
github + filesystem + git

端到端贡献:本地克隆仓库、进行更改、推送分支、打开 PR — 无需离开聊天

本地克隆 acme/widgets,修复 src/utils/format.ts:42 中的打字错误,推送到新分支,打开 PR。✓ 已复制

工具

此 MCP 暴露的能力

工具输入参数何时调用成本
search_issues owner: str, repo: str, labels?: str[], state?: str 你想通过标签、状态、受托人或活动找出 issues 1 GitHub API call
get_issue owner: str, repo: str, issue_number: int 在 search_issues 之后,当你需要完整的对话时 1 API call
create_issue owner, repo, title, body, labels?, assignees? 提交新 issue — 确保用户确实想要这个 1 API call (write)
list_pull_requests owner, repo, state?, sort?, base?, head? 通过状态/分支/作者找出 PR 1 API call
get_pull_request owner, repo, pull_number 读取特定 PR 的 diff 和元数据 1 API call
merge_pull_request owner, repo, pull_number, merge_method? 仅当明确告知时 — 先使用 dry-run 讨论 1 API call (write, irreversible)
search_code q: str, sort? 在整个组织中找出符号使用 1 API call (lower rate limit: 30/min)
get_file_contents owner, repo, path, ref? 从仓库中读取单个文件,无需克隆 1 API call
create_or_update_file owner, repo, path, message, content, sha? 一次性文件编辑;对于多文件更改,使用分支 + PR 1 API call (write)
list_commits owner, repo, sha?, path? 审计文件或分支的历史 1 API call

成本与限制

运行它的成本

API 配额
个人 PAT:5,000 请求/小时。GitHub App:15,000/h。代码搜索:个人 30/分钟,分开计算。
每次调用 Token 数
issue/PR 元数据 200–500 tokens;大文件获取可能膨胀到 5k+
费用
任何 GitHub 账户都免费。GitHub Enterprise 有更高的限制。
提示
如果达到限制,切换到 GitHub App — 比管理多个 PAT 更简单,速率提高 3 倍。迭代时缓存 list_issues 结果。

安全

权限、密钥、影响范围

最小权限: repo:read issues:read
凭据存储: 细粒度 PAT 放在环境变量中(如 GITHUB_PERSONAL_ACCESS_TOKEN)。永远不要提交到配置文件。
数据出站: 所有 API 调用仅到 api.github.com。无第三方遥测。
切勿授予: admin:org delete_repo admin:enterprise

故障排查

常见错误与修复

401 Unauthorized

你的 PAT 过期或没有访问该仓库的权限。在 github.com/settings/tokens 中使用正确的范围重新创建。

验证: curl -H "Authorization: Bearer $GITHUB_PERSONAL_ACCESS_TOKEN" https://api.github.com/user
403 rate limit exceeded

你在个人 PAT 上达到了 5000 req/h。等待重置窗口,或迁移到 GitHub App token(15k/h)。

验证: curl -H "Authorization: Bearer $TOKEN" https://api.github.com/rate_limit
404 Not Found on a private repo

PAT 在其允许仓库列表中不包含该仓库。编辑细粒度 PAT 并添加仓库。

Docker: 'unable to find image'

首先拉取镜像:docker pull ghcr.io/github/github-mcp-server。如果它是私有的,检查你是否已验证 ghcr.io。

验证: docker images | grep github-mcp-server

替代方案

GitHub 对比其他方案

替代方案何时用它替代权衡
GitLab MCP你使用 GitLab.com 或自托管 GitLab 而不是 GitHub功能面较小,由社区维护
Gitea MCP自托管 Gitea 安装相比官方 GitHub MCP 的工具有限
git MCP只需要本地 git 操作(status、log、diff、blame),无需任何远程没有 issues、PRs 或远程操作 — 在任何本地仓库上无需认证工作

更多

资源

📖 阅读 GitHub 上的官方 README

🐙 查看未解决的 issue

🔍 浏览全部 400+ MCP 服务器和 Skills