Claude Code 配置 GitHub：GitHub MCP Server 完整步骤
简答：如果你只是让 Claude Code 操作当前电脑里的 GitHub 项目，进入仓库目录后运行 claude 即可；如果还要查询远程仓库、Issue 或 Pull Request，则需要添加 GitHub MCP Server。当前 GitHub 官方安装指南对 Claude Code 2.1.1 及更高版本给出 add-json 格式，对 2.1.0 及更早版本给出旧版 --transport http 格式；添加后重启 Claude Code，再用 claude mcp list 和 claude mcp get github 检查。
定义：Claude Code 配置 GitHub，通常是把本地仓库交给 Claude Code 使用 Git，或通过 GitHub MCP Server 让它调用 GitHub 的远程仓库、Issue 和 Pull Request 能力。
先判断：你需要本地 Git，还是 GitHub MCP
搜索“Claude Code 配置 GitHub”时，最容易混淆的是两种不同需求。第一种是本地 Git 工作流：你已经把 GitHub 仓库克隆到电脑，只希望 Claude Code 查看文件、运行 git status、创建提交或协助修改代码。此时进入仓库目录后启动 claude，不需要额外配置 GitHub MCP。
第二种是GitHub MCP 远程能力：你希望 Claude Code 查询远程仓库信息、Issue、Pull Request 或其他 GitHub API 能力。这时才需要按照 GitHub 官方安装指南添加远程 MCP Server。Claude Code 官方文档也把 MCP 作为连接外部工具的配置方式之一。可先按下面的表格选择路径。
| 你的目标 | 是否需要 GitHub MCP | 先做什么 |
|---|---|---|
| 修改当前已克隆的项目 | 不需要 | 进入仓库目录，运行 claude |
| 让 Claude Code 查询远程 Issue 或 Pull Request | 需要 | 准备 GitHub Token，再添加 MCP Server |
| 团队共享 MCP 配置 | 需要 | 使用项目级配置，但不要提交真实 Token |
| 所有项目都使用同一个 GitHub MCP | 需要 | 根据当前版本使用 --scope user |
本文重点讲第二种：在 Claude Code 中配置 GitHub MCP Server。命令和版本边界以 GitHub 当前安装指南为准，本文检索日期为 2026 年 10 月 27 日。参考：GitHub MCP Server 的 Claude 安装指南、Claude Code 官方最佳实践。
配置前准备：安装 Claude Code 和创建 Token
先确认终端可以找到 Claude Code：
- macOS 或 Linux：
curl -fsSL https://claude.ai/install.sh | bash - Windows PowerShell：
irm https://claude.ai/install.ps1 | iex - Homebrew：
brew install --cask claude-code - WinGet：
winget install Anthropic.ClaudeCode
安装后可以进入一个已经克隆的项目目录，运行 claude。如果出现 claude: command not found，先检查官方文档提到的安装目录是否已经加入 PATH；不要在尚未确认 PATH 的情况下重复安装。
接下来创建 GitHub Personal Access Token。GitHub 官方建议优先使用细粒度 Token，因为它可以限定资源所有者、具体仓库和权限。创建路径是 GitHub 头像 → Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token。
权限选择遵循最小化原则：
- 只选择确实需要访问的资源所有者。
- Repository access 优先选择指定仓库，而不是全部仓库。
- 只开启当前任务需要的 Repository、Organization 或 Account 权限。
- 设置有效期，任务结束后删除不再需要的 Token。
如果组织要求审批，细粒度 Token 可能处于待批准状态；这时即使命令格式正确，也可能无法访问组织仓库。权限和组织策略应以 GitHub 当前页面为准。参考：GitHub 管理个人访问令牌。
主流程：按 Claude Code 版本添加远程 GitHub MCP
先在项目目录外或项目目录的终端中查看 Claude Code 版本：
claude --version
根据 GitHub 官方安装指南，Claude Code 2.1.1 及更高版本使用 claude mcp add-json 格式。将下面的 YOUR_GITHUB_PAT 替换成真实 Token：
claude mcp add-json github '{"type":"http","url":"https://api.githubcopilot.com/mcp","headers":{"Authorization":"Bearer YOUR_GITHUB_PAT"}}'
这条命令会把 Token 放进命令参数，因此更适合临时测试，不建议把完整命令写入脚本、终端历史或团队文档。GitHub 官方指南明确建议避免硬编码 Token，并给出了使用环境变量或 .env 文件的方式。
如果你的版本是 Claude Code 2.1.0 或更早版本，使用官方给出的旧格式：
claude mcp add --transport http github https://api.githubcopilot.com/mcp -H "Authorization: Bearer YOUR_GITHUB_PAT"
Windows PowerShell 如果提示 missing required argument 'name'，GitHub 指南给出的兼容写法是把服务器名称紧跟在 claude mcp add 后面：
$pat = "YOUR_GITHUB_PAT"
claude mcp add github --transport http https://api.githubcopilot.com/mcp/ -H "Authorization: Bearer $pat"
另外，GitHub 官方页面特别提醒：Windows 或 CLI 使用 add-json 添加 HTTP Server 时可能出现 Invalid input。这不是让你随意改参数，而是应先尝试该页面列出的旧格式，并结合本机的 claude mcp add --help 核对当前 CLI 参数。
若想改变配置作用范围，GitHub 指南当前列出的范围含义是：
local：默认值，只对当前项目中的你本人可用。project：写入项目级.mcp.json，可供项目成员共享配置。user：对你参与的多个项目可用。
例如，确认命令无误后，可以在命令末尾增加 --scope user。是否使用项目级范围，要结合团队仓库的密钥管理方式，不要因为“共享配置”就把个人 Token 提交进 Git。
以上命令、URL、版本边界和验证命令均来自：GitHub MCP Server 官方 Claude 安装指南。
安全保存 Token：配置可以共享，密钥不要共享
最小实践是把 Token 放在本地环境文件中，并将密钥文件和可能包含认证信息的 MCP 配置加入 .gitignore。例如：
GITHUB_PAT=your_token_here
echo -e ".env\n.mcp.json" >> .gitignore
Linux 或 macOS 可以先从 .env 读取变量，再执行官方示例的远程添加命令：
export GITHUB_PAT="$(grep '^GITHUB_PAT=' .env | cut -d '=' -f2-)"
claude mcp add-json github '{"type":"http","url":"https://api.githubcopilot.com/mcp","headers":{"Authorization":"Bearer '\"$GITHUB_PAT\"'"}}'
Windows PowerShell 可以使用 GitHub 指南给出的读取方式：
$githubPatLine = Get-Content .env | Select-String "^\s*GITHUB_PAT\s*=" | Select-Object -First 1
$env:GITHUB_PAT = ($githubPatLine.Line -split "=", 2)[1].Trim().Trim('"').Trim("'")
claude mcp add-json github "{`"type`":`"http`",`"url`":`"https://api.githubcopilot.com/mcp`",`"headers`":{`"Authorization`":`"Bearer $env:GITHUB_PAT`"}}"
需要注意三点：第一，.env 也可能被日志、备份或同步工具暴露；第二，项目级 .mcp.json 即使没有 Token，也应先检查是否包含其他敏感字段；第三，Token 一旦出现在 Shell 历史、进程参数或日志中，应及时撤销并重新创建。GitHub 官方也建议为 Token 设置有效期，并在不再需要时删除。
添加后如何验证：先看配置，再做只读请求
完成添加后重启 Claude Code，然后在终端执行：
claude mcp list
claude mcp get github
官方安装指南将这两个命令列为验证方式。第一条用于确认服务器是否出现在列表中，第二条用于查看名为 github 的具体配置。
进入 Claude Code 后，再使用 /mcp 查看当前 MCP 连接状态。首次连接如果出现授权或批准提示，只批准你确认过名称、URL 和用途的服务器。
验证问题建议从只读任务开始，例如：“读取我有权限访问的 owner/repo 仓库基本信息，只返回仓库名称、可见性和默认分支，不执行写操作。”这样可以把问题拆成三层：服务器是否已加载、Token 是否有效、Token 是否拥有该仓库权限。不要一开始就让 Claude 创建 Issue、修改 Pull Request 或执行写操作。
如果你只是要确认本地仓库连接，不必依赖 MCP：进入 GitHub 项目目录后运行 git remote -v 和 git status，确认远程地址与当前工作区即可。
常见报错排查清单
| 现象 | 优先检查 | 处理方式 |
|---|---|---|
Invalid input | Claude Code 版本和命令格式 | 2.1.1 及以上先用 add-json；Windows 仍失败时尝试官方列出的旧格式，并运行 claude mcp add --help 核对参数。 |
missing required argument 'name' | 服务器名称位置 | PowerShell 旧格式中将 github 放在 claude mcp add 后面。 |
| 列表中没有 github | 命令是否在终端执行、是否重启 | 退出并重新打开 Claude Code，再运行 claude mcp list 和 claude mcp get github。 |
| 401 或认证失败 | Token 是否复制完整、是否已撤销或过期 | 重新检查 Token，确认 Authorization 使用 Bearer 前缀；不要把 Token 直接发到聊天或工单。 |
| 403 或组织仓库无法访问 | 仓库范围、权限和组织审批 | 检查细粒度 Token 是否选中目标仓库，组织是否要求批准，以及该 API 能力是否需要更高权限。 |
| 能访问公开仓库但不能访问私有仓库 | Token 资源范围 | 在 GitHub Token 页面确认资源所有者和 Selected repositories 设置，不要直接改成全部仓库。 |
| 连接超时 | 网络、代理和企业防火墙 | 先确认终端能访问 GitHub MCP 使用的 URL；若处于企业网络，向管理员确认代理策略，不要擅自绕过安全控制。 |
401、403 并不都代表命令写错：它们也可能来自 Token 状态、仓库范围、组织审批或网络策略。排查时先用 claude mcp get github 确认 URL 和认证字段，再单独检查 GitHub Token 页面。
团队项目怎么放配置
如果配置只供个人使用，可以采用默认的 local 范围或 user 范围；如果团队需要共享服务器定义，可以采用项目级 .mcp.json，但共享文件中不要放个人 Token。
更稳妥的团队流程是：仓库提交不含秘密的服务器配置，成员各自按组织规则提供自己的 Token；提交前使用 git diff -- .mcp.json .env 检查是否出现密钥片段，并将 .env 加入 .gitignore。若 Token 已经提交到仓库、日志或截图中，应立即在 GitHub 中删除该 Token，再按最小权限重新创建。
Claude Code 的权限设置和 MCP 配置是不同层面：MCP 负责连接外部工具，Claude Code 的权限规则负责决定哪些命令或操作需要批准。不要因为已经配置了 MCP，就默认允许所有写操作。
常见问题
Claude Code 配置 GitHub 一定要创建 Token 吗？
如果只是进入本地已克隆仓库，让 Claude Code 使用本机 Git，通常不需要额外的 GitHub MCP Token。如果要调用远程 GitHub MCP Server，则 GitHub 官方安装指南提供了 Personal Access Token 认证方式；也可以根据官方支持的本地部署方式使用 OAuth。
Claude Code 2.1.1 和 2.1.0 的 GitHub MCP 命令有什么区别？
GitHub 当前安装指南写明，2.1.1 及更高版本使用 <code>claude mcp add-json</code>；2.1.0 及更早版本使用 <code>claude mcp add --transport http</code>。如果 Windows 使用 add-json 出现 <code>Invalid input</code>，应参考同一指南中的旧格式和 PowerShell 写法，而不是自行猜测参数。
为什么 claude mcp list 看不到 github？
先确认命令是在系统终端执行，而不是输入到 Claude Code 对话中；然后重启 Claude Code，再运行 <code>claude mcp list</code> 和 <code>claude mcp get github</code>。如果仍不存在，运行 <code>claude mcp add --help</code> 检查当前版本的参数格式，并核对服务器名称是否确实是 <code>github</code>。
GitHub MCP 返回 403，应该给 Token 增加全部权限吗？
不建议直接增加全部权限。先检查细粒度 Token 的资源所有者、Selected repositories、组织审批状态和具体权限。GitHub 官方文档说明细粒度 Token 可以限制到指定仓库和权限范围，但不同 API 端点需要的权限并不相同。
项目里的 .mcp.json 能不能直接提交到 Git？
是否提交取决于文件内容。如果只包含不带秘密的服务器定义，团队可以评估是否提交；如果含有 Token、环境变量值或其他敏感字段，就不应提交。无论是否提交，都应将 .env 加入 .gitignore，并在提交前检查 diff。