如何在 Claude Code 中安装 GitHub MCP（远程或本地）

简短回答

要在 Claude Code 中安装 GitHub MCP，先创建一个 GitHub 个人访问令牌（PAT），然后运行 claude mcp add --transport http github https://api.githubcopilot.com/mcp/ --header "Authorization: Bearer $GITHUB_PAT"，启动 claude，在 /mcp 中确认 github 带有对勾。这样连接的是 GitHub 官方托管的服务器，无需安装，也不用自己更新。

如果不想管理令牌，也可以用 Docker 在本地运行服务器：首次使用时它会在浏览器中打开 GitHub 登录页，并且只在内存中保存令牌。两种方式使用的都是来自 github/github-mcp-server 的官方 GitHub MCP 服务器。

远程还是本地？

大多数人应该从远程开始。如果你想用 OAuth 代替长期有效的令牌、需要 GitHub Enterprise Server，或者必须让流量留在本机，就选本地。

前置条件

• 已安装 Claude Code。按 GitHub 官方指南的建议，在项目目录中打开它，让配置作用范围更清晰。
• 远程服务器或基于 PAT 的本地配置需要一个 GitHub 个人访问令牌。在 github.com/settings/personal-access-tokens/new 创建。
• 如果选本地 Docker 方案，需要安装并运行 Docker。

创建令牌

只授予需要的权限。GitHub README 列出了以下经典权限范围作为基础：

如果使用细粒度令牌，选择具体的仓库，以及与你打算启用的工具集相匹配的权限。你的组织也可能限制 PAT 或要求审批。每个项目用不同的令牌，定期轮换，绝不提交到仓库。

把令牌放进环境变量或被 gitignore 的 .env 文件中，避免留在 shell 历史里：

export GITHUB_PAT="your_token_here"   # placeholder, not a real token

方案 1：远程服务器（推荐）

第 1 步：添加服务器

Claude Code MCP 文档中的写法：

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer $GITHUB_PAT"

GitHub 的 Claude 安装指南对 Claude Code 2.1.1 及更新版本使用 add-json：

claude mcp add-json github \
  '{"type":"http","url":"https://api.githubcopilot.com/mcp","headers":{"Authorization":"Bearer '"$GITHUB_PAT"'"}}'

两者保存的内容相同。shell 会在 Claude Code 读取之前把 $GITHUB_PAT 替换成真实值，所以 Claude Code 配置里保存的是令牌本身，而不是变量名。

第 2 步：选择作用域

使用 project 作用域时，绝不要把令牌写进 .mcp.json。Claude Code 会展开这个文件中的环境变量，所以提交下面的内容，让每个成员自己设置 GITHUB_PAT：

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${GITHUB_PAT}"
      }
    }
  }
}

远程服务器能用 OAuth 吗？

GitHub README 指出，远程服务器的 OAuth 要求每个宿主应用都注册了 GitHub App 或 OAuth App，而任何支持远程服务器的宿主都可以使用 PAT 认证。因此 GitHub 的 Claude 指南使用的是 PAT。如果你想用浏览器登录代替令牌，下面的本地服务器内置了 OAuth。

方案 2：用 Docker 运行本地服务器

OAuth 登录（无需令牌）

官方镜像内置了 GitHub 的 OAuth 应用凭据，所以在 github.com 上你什么都不用提供。只需把固定的回调端口发布到回环地址：

claude mcp add github -e GITHUB_OAUTH_CALLBACK_PORT=8085 -- \
  docker run -i --rm -p 127.0.0.1:8085:8085 \
  -e GITHUB_OAUTH_CALLBACK_PORT ghcr.io/github/github-mcp-server

首次调用工具时，服务器会打开 GitHub 的授权页面。令牌只保存在内存中，所以服务器重启后需要重新登录。

使用 PAT

PAT 的优先级高于 OAuth：

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

注意 -e 出现了两次：一次在 -- 之前（由 Claude Code 设置变量），一次在 docker run 命令里（由 Docker 传入容器）。

不用 Docker：发布版二进制

从发布页面下载二进制并加入 PATH。使用官方构建时，OAuth 不需要任何参数，会随机选择一个回环端口：

claude mcp add github -- github-mcp-server stdio

或者按 GitHub 指南使用 PAT：

claude mcp add-json github \
  '{"command":"github-mcp-server","args":["stdio"],"env":{"GITHUB_PERSONAL_ACCESS_TOKEN":"YOUR_GITHUB_PAT"}}'

工具集、只读模式和 Lockdown

服务器默认启用 context、repos、issues、pull_requests 和 users 这几个工具集。只启用需要的工具集，可以帮助 Claude 选对工具，也能减少上下文占用。其他工具集包括 actions、code_security、dependabot、discussions、gists、notifications、orgs、projects、labels 等；all 会启用全部。

一个只读、限定在 repos、issues 和 pull requests 的远程配置，写成 .mcp.json 条目如下：

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${GITHUB_PAT}",
        "X-MCP-Toolsets": "repos,issues,pull_requests",
        "X-MCP-Readonly": "true"
      }
    }
  }
}

Lockdown 模式会在公开仓库中隐藏没有推送权限的作者所发布的内容。它是防御来自不可信 Issue 和评论的提示词注入的尽力而为的过滤器，并非安全边界，但当 Claude 读取公开仓库时值得开启。参见 MCP 安全最佳实践。

验证连接

claude mcp list
claude mcp get github

在会话中，/mcp 应显示 github 带有对勾。claude mcp add 不会校验凭据，所以错误的令牌在添加时也会被接受，只会在这里失败，并在失败详情中显示 401。

示例提示词

• 「列出这个仓库中所有打开的 Pull Request，并总结每个改了什么。」
• 「读一下 Issue 123，找到它提到的代码，并给出修复方案。」
• 「main 分支上最近一次 GitHub Actions 运行为什么失败？给我看失败的步骤。」
• 「创建一个分支，提交我们刚才的修改，并开一个关联 Issue 123 的草稿 PR。」
• 「审查 PR 45，对看起来有风险的地方留下评论。」
• 「这个仓库里有没有未处理的 Dependabot 或代码扫描告警？」

最后两个需要启用 actions、dependabot 或 code_security 工具集，并且令牌有对应权限。

故障排查

已经在用 gh CLI 了？Claude Code 可以通过 shell 调用它，很多任务不需要 MCP 也能完成。当你需要结构化的工具、工具集限制、只读模式和 Lockdown，而不是开放 shell 权限时，MCP 服务器才真正体现价值。

下一步

连上 GitHub 之后，可以再加一些为它提供工作的服务器：用 Playwright MCP 在开 PR 之前先在浏览器里验证修复，或用 Supabase MCP 处理数据库变更。更多开发工具可以在 MCP 服务器目录中浏览，作用域、OAuth 和服务器管理请看 Claude Code MCP 指南。