1. 为什么要在 Claude Code 里接 Github MCP Server
如果你已经在用 Claude Code 写代码，大概率遇到过这种场景：想让 AI 帮你查一下某个仓库最近的 PR、看看 issue 列表、或者直接读某个文件的内容，结果它只能干巴巴地告诉你「我无法访问外部服务」。这时候 Github MCP Server 就是那个把 Claude Code 从「只会聊天的助手」变成「能动手干活的工程搭档」的关键组件。
MCP 全称 Model Context Protocol，你可以把它理解成 Claude Code 和外部工具之间的一套标准插头。Github MCP Server 就是官方提供的一个插头，插上之后 Claude Code 就能调用 Github 的仓库、Issue、PR、代码搜索等能力。听起来很美好，但真正动手配置的时候，很多人会卡在三个地方：一是鉴权通道不统一，本地一把 Key、CI 一把 Key、团队共享又一把 Key，管理起来很乱；二是 settings.json 的写法容易写错，尤其是 Windows 下 Docker 路径和 WSL 的配合；三是配完了不知道怎么验证到底通没通，只能靠猜。
这篇内容聚焦的就是「统一鉴权通道」这个角度。也就是说，不管你是在本地开发、还是在自动化脚本里跑 Claude Code，都让它走同一个 Base URL 和同一套 Key 管理逻辑，而不是每个环境各配一套。这样做的直接好处是：换 Key 只改一个地方，排查问题时链路清晰，团队协作时也不会出现「我这边能跑你那边报 401」的尴尬。
适合读这篇的人有三类：第一类是本机已经装了 Claude Code、想扩展 Github 能力的个人开发者；第二类是需要把 Claude Code 接入仓库自动化流程的工程团队；第三类是被 401、local proxy failed 这类报错折腾过、想一次性把配置理顺的人。下面我会从环境准备讲到 settings 片段，再到连通性验证和报错排查，每一步都给可复制的内容。
2. 前置准备：Docker、WSL 与 Github CLI 的安装要点
在动 settings.json 之前，有几个前置组件必须先到位，否则后面配好了也跑不起来。这一节按 Windows 环境来讲，Mac 和 Linux 用户可以直接跳过 WSL 部分。
2.1 Docker Desktop 与 WSL2 的关系
Github 官方的 MCP Server 是以容器镜像形式分发的，所以你需要 Docker 来跑它。Windows 上 Docker Desktop 依赖 WSL2 作为后端，所以这两件事要一起搞定。先去 Docker 官网下载对应架构的安装包，x86 机器选 amd64，ARM 机器选 arm64。安装完启动，如果报「virtualisation support wasn't detected」，说明底层虚拟化没开。
开启分两步。第一步进 BIOS/UEFI，Intel CPU 找 Intel Virtualization Technology 或 VT-x，AMD CPU 找 AMD-V 或 SVM Mode，设为 Enabled 后保存重启。第二步在 Windows 里启用系统组件，用管理员权限打开 PowerShell，依次执行：
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart dism.exe /online /enable-feature /featurename:HypervisorPlatform /all /norestart dism.exe /online /enable-feature /featurename:Containers /all /norestart执行完重启电脑，再回来配置 WSL2 为默认版本：
wsl --update wsl --set-default-version 2 wsl --statuswsl --update如果下载很慢，可以去 Github 的 microsoft/WSL releases 页面手动下载对应版本的 msi 离线包，双击安装即可。装完之后再启动 Docker Desktop，应该就不会再报虚拟化错误了。
2.2 安装 Github CLI 并登录
Github CLI 不是 MCP Server 运行的硬依赖，但它能帮你快速生成和验证 Token，省去在网页上点来点去的麻烦。用 winget 安装：
winget install GitHub.cli装完关掉 PowerShell 重开，验证版本：
gh --version然后登录，按提示选「GitHub.com」和「浏览器登录」最省事：
gh auth login登录成功后，你可以用gh auth token直接拿到当前登录的 Token，这个 Token 后面会用到。不过要注意，gh auth token拿到的 Token 权限范围可能不够，如果后面调用 Github MCP 时报权限错误，还是需要去网页端手动生成一个带 repo、read:org 等 scope 的 Personal Access Token。
2.3 生成 Github Personal Access Token
打开 Github 网页，进入 Settings → Developer settings → Personal access tokens，选择生成一个 fine-grained token 或者 classic token。classic token 配置简单，勾选 repo、read:org、workflow 这几个 scope 基本够用。生成后复制那串ghp_开头的字符串，它只显示一次，丢了就得重新生成。
这里有个统一鉴权的关键点：这个 PAT 不要散落在多个配置文件里。后面我们会把它集中放在一个环境变量或者统一的 settings 片段中，让 Claude Code 和 MCP Server 都从这里读。
3. 可复制的 settings 配置与 MCP Server 注册
这一节是核心，我会给出两种注册方式：一种是命令行快速注册，适合临时验证；另一种是写进 settings.json，适合长期使用和团队共享。两种方式都指向同一个鉴权通道。
3.1 命令行方式注册 Github MCP Server
Claude Code 提供了claude mcp add命令，可以在终端里直接注册一个 MCP Server。注意这个命令要在终端里执行，不是在 Claude Code 的对话界面里执行：
claude mcp add -s user --transport http github https://api.githubcopilot.com/mcp -H "Authorization: Bearer YOUR_PAT_HERE"这里的-s user表示注册到用户级别，所有项目都能用；--transport http表示走 HTTP 传输；后面的-H是带上鉴权头。把YOUR_PAT_HERE换成你刚才生成的 PAT。这种方式的好处是快，缺点是 Key 明文写在命令历史里，不太适合团队环境。
3.2 settings.json 方式注册（推荐长期使用）
更稳妥的做法是写进 Claude Code 的 settings.json。Windows 下路径通常是C:\Users\你的用户名\.claude\settings.json，Mac/Linux 是~/.claude/settings.json。如果你用的是 Docker 方式跑 MCP Server，配置片段如下：
{ "mcpServers": { "github": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server" ], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_PAT_HERE" } } } }这段配置的意思是：Claude Code 启动时，会用 docker run 拉起ghcr.io/github/github-mcp-server这个镜像，并把GITHUB_PERSONAL_ACCESS_TOKEN这个环境变量传进去。-i保持标准输入打开，--rm容器退出后自动清理，不会在你机器上留一堆停止的容器。
如果你不想用 Docker，想走 HTTP 方式，可以改成这样：
{ "mcpServers": { "github": { "type": "http", "url": "https://api.githubcopilot.com/mcp", "headers": { "Authorization": "Bearer YOUR_PAT_HERE" } } } }两种方式选一种即可，不要同时配，否则 Claude Code 可能会加载两个同名的 github server，行为不确定。
3.3 统一鉴权通道的写法
所谓统一鉴权通道，核心思路是：不要让 PAT 硬编码在多个地方。你可以把 PAT 放到系统环境变量里，比如命名为GITHUB_MCP_TOKEN，然后在 settings.json 里引用它。不过 Claude Code 的 settings.json 对变量插值的支持有限，更实际的做法是维护一个「配置模板」，团队里每个人复制模板后只改一处 PAT。
如果你同时在用 TaoToken 作为模型调用的统一入口，可以把模型侧的 Base URL 和 Key 也放在同一个 settings 文件里管理，这样整个 Claude Code 的外部依赖就只有两个来源：模型走 TaoToken，工具走 Github MCP。模型侧的配置片段大致是这样：
{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "YOUR_TAOTOKEN_KEY" } }把这段和上面的 mcpServers 合并到同一个 settings.json 里，就是一个完整的、鉴权通道统一的配置。模型请求走 TaoToken 的 API 地址，Github 工具请求走 Github MCP，两边互不干扰，但都在一个文件里可查可改。
4. 验证请求与成功结果确认
配置写完了不代表就通了，必须做一次实际的连通性验证。这一步很多人跳过，结果等到真正用的时候才发现问题，排查成本更高。
4.1 重启 Claude Code 并检查 MCP 加载状态
改完 settings.json 后，完全退出 Claude Code 再重新打开，让它重新读取配置。然后在 Claude Code 里输入：
/mcp这个命令会列出当前加载的所有 MCP Server。如果你看到 github 出现在列表里，状态是 connected 或 ready，说明配置被正确读取了。如果没看到，或者状态是 failed，说明配置有问题，先去看第 5 节的排查。
4.2 用自然语言触发 Github 能力
加载成功后，直接向 Claude Code 发问，比如：
List my GitHub repositories或者更具体一点：
帮我看看 xxx 仓库最近的 5 个 pull request如果配置正确，Claude Code 会调用 Github MCP Server，返回你的仓库列表或 PR 信息。第一次调用可能会慢几秒，因为 Docker 要拉镜像或者启动容器。成功返回结果就说明整条链路通了：Claude Code → MCP Server → Github API。
4.3 用命令行单独验证 MCP Server
如果你想绕过 Claude Code，单独验证 MCP Server 本身能不能跑，可以直接用 docker 命令测试：
docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN=YOUR_PAT_HERE ghcr.io/github/github-mcp-server如果容器能正常启动并等待输入，说明镜像和 Token 都没问题。如果报错，错误信息会直接告诉你原因，比如 Token 无效、镜像拉不下来等。这一步能把「MCP Server 本身的问题」和「Claude Code 配置的问题」分开，排查时很有用。
5. 本篇常见报错排查
配置过程中最容易遇到的就是下面这几类报错，我按实际出现频率排一下，并给出对应的处理方式。
5.1 401 Unauthorized
这是最常见的。原因通常是 PAT 无效、过期、或者权限 scope 不够。先确认你复制 PAT 的时候没有多复制空格，然后去 Github 网页检查这个 Token 是否还在有效期内。如果是 fine-grained token，确认它被授权访问了你想要操作的仓库。classic token 的话，确认勾选了 repo 和 read:org。改完 Token 后记得重启 Claude Code。
5.2 local proxy failed 或连接超时
这个报错通常出现在 HTTP 传输方式下，说明 Claude Code 无法连接到https://api.githubcopilot.com/mcp。先检查你的网络能不能正常访问这个地址，可以用 curl 测一下：
curl -I https://api.githubcopilot.com/mcp如果连不上，可能是本地网络策略或者 DNS 的问题。这种情况下，改用 Docker 方式注册 MCP Server 往往能绕过，因为 Docker 容器内的网络栈和宿主机不完全一样。另外检查一下 settings.json 里有没有残留的 proxy 配置，有的话先注释掉再试。
5.3 reading choices 相关报错
这个报错一般出现在模型返回阶段，提示解析响应时读不到 choices 字段。它通常不是 Github MCP 本身的问题，而是模型侧的返回格式不符合预期。如果你用的是 TaoToken 作为模型入口，先确认ANTHROPIC_BASE_URL填的是https://taotoken.net/api，Key 没有过期。然后确认你请求的模型 ID 是有效的。可以在 TaoToken 的模型对话页面先单独测一下模型能不能正常返回，排除模型侧问题后再回来看 MCP。
5.4 OAuth 相关报错
如果你用的是需要 OAuth 的 Github 集成方式，可能会遇到 OAuth token 过期或回调失败。Github MCP Server 用 PAT 方式是不需要 OAuth 的，所以如果你遇到 OAuth 报错，先检查是不是配置里混入了 OAuth 相关的字段。最干净的做法是删掉 settings.json 里 github 那段，重新用第 3 节的 PAT 方式配一遍。
5.5 Docker 容器启动失败
报错信息里如果出现docker: command not found，说明 Docker 没装好或者没加到 PATH。Windows 下确认 Docker Desktop 正在运行，托盘图标是绿色的。如果报Cannot connect to the Docker daemon，说明 Docker 服务没起来，重启 Docker Desktop 即可。还有一种情况是镜像拉取失败，可以手动先拉一次：
docker pull ghcr.io/github/github-mcp-server拉成功了再让 Claude Code 去启动，就不会卡在拉镜像这一步。
6. 把配置沉淀成可复用的接入方案
配置跑通之后，建议做一件事：把这份 settings.json 沉淀成团队或个人的标准模板。模板里模型侧统一走 TaoToken 的 API 地址，工具侧统一走 Github MCP，PAT 和 API Key 用占位符标出来，谁用谁填。这样下次换机器、换项目、或者新同事入职，直接复制模板改两个值就能跑，不用再从头踩一遍 Docker 和 WSL 的坑。
如果你还想把这套配置用到更长期的编码场景里，比如让 Claude Code 持续帮你处理仓库里的 issue 和 PR，可以了解一下 Coding Plan 这类长期方案，它和单次 API 调用是互补的。模型对话页面可以用来快速验证模型侧是否正常，接入文档里则写了 Base URL、Key 和 Model ID 这三件套的完整说明。把 Github MCP 的配置和模型侧的配置放在同一个 settings 文件里管理，是我目前觉得最省心的做法，排查问题时只需要看一个文件，不用在多个地方来回找。
