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 机器选 amd64ARM 机器选 arm64。安装完启动如果报「virtualisation support wasnt detected」说明底层虚拟化没开。开启分两步。第一步进 BIOS/UEFIIntel CPU 找 Intel Virtualization Technology 或 VT-xAMD 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 ServerClaude 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.jsonMac/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_TOKENYOUR_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/apiKey 没有过期。然后确认你请求的模型 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 MCPPAT 和 API Key 用占位符标出来谁用谁填。这样下次换机器、换项目、或者新同事入职直接复制模板改两个值就能跑不用再从头踩一遍 Docker 和 WSL 的坑。如果你还想把这套配置用到更长期的编码场景里比如让 Claude Code 持续帮你处理仓库里的 issue 和 PR可以了解一下 Coding Plan 这类长期方案它和单次 API 调用是互补的。模型对话页面可以用来快速验证模型侧是否正常接入文档里则写了 Base URL、Key 和 Model ID 这三件套的完整说明。把 Github MCP 的配置和模型侧的配置放在同一个 settings 文件里管理是我目前觉得最省心的做法排查问题时只需要看一个文件不用在多个地方来回找。