Claude学院

Claude 连接 GitHub：MCP 连接器配置实战

把 Claude 连上 GitHub，靠的是 MCP（模型上下文协议）连接器：在 Claude 桌面版里添加 GitHub 远程连接器并完成 OAuth 授权，或在 Claude Code 里用一条命令注册 GitHub MCP 服务器，Claude 就能直接读取仓库代码、搜索 issue、查看 PR、提交改动。下面分桌面版和命令行两条路径，把每一步参数和命令讲清楚。

先搞清楚：MCP 连接 GitHub 的两种形态

GitHub 官方提供了 MCP 服务器，它有两种部署形态，决定了你的配置方式：

  • 远程 GitHub MCP 服务器：托管在 GitHub 侧，地址为 https://api.githubcopilot.com/mcp/，用 OAuth 授权，无需本地安装任何东西。桌面版连接器和 Claude Code 都推荐用这个。
  • 本地 GitHub MCP 服务器：用 Docker 在本机跑 ghcr.io/github/github-mcp-server 镜像，靠 Personal Access Token（PAT）鉴权。适合需要离线、自定义网络策略或企业内网的场景。

如果你还不清楚 MCP 到底是什么、为什么需要它，建议先读 MCP 是什么？一篇讲清 Claude 模型上下文协议，再回来看本文会顺畅很多。

方案一：桌面版连接器接入 GitHub（最简单）

Claude 桌面版（macOS / Windows）内置了连接器（Connectors）面板，连 GitHub 不用碰任何配置文件。

  1. 打开 Claude 桌面版，进入 设置 → 连接器（Settings → Connectors）。
  2. 点击 添加连接器，在目录里找到 GitHub；如果目录里没有，选择 添加自定义连接器，类型选 Remote (URL)，URL 填 https://api.githubcopilot.com/mcp/。
  3. 点击连接，浏览器会跳转到 GitHub 的 OAuth 授权页。这里要注意授权范围：如果只让 Claude 读代码、看 issue，授予只读权限即可；要让它提交、建分支、开 PR，才勾选仓库写入权限。
  4. 授权完成后回到 Claude，连接器状态变为已连接。新建对话时，在输入框的工具图标里能看到 GitHub 提供的工具列表（如 search_repositories、get_file_contents、create_issue 等）。

连好后直接用自然语言指挥即可，例如「列出我 my-org/web-app 仓库里最近 5 个开着的 issue」。Claude 会调用对应的 MCP 工具完成查询。桌面版连接器的通用设置细节，可参考 Claude MCP 怎么配置？桌面版连接器设置教程。

方案二：Claude Code 命令行接入 GitHub（开发者首选）

如果你在终端里用 Claude Code 写代码，把 GitHub MCP 装进去能让它在编码时直接查仓库、看 PR diff。Claude Code 是 Anthropic 官方命令行工具，用 claude mcp add 注册服务器。

用远程服务器（推荐）

claude mcp add --transport http github https://api.githubcopilot.com/mcp/

执行后 Claude Code 会引导你完成 OAuth 授权（在浏览器里登录 GitHub 并确认权限）。授权令牌由 Claude Code 安全保存，不会明文写进配置文件。注册完用下面命令确认状态：

claude mcp list

看到 github 一行显示 ✓ connected 就成功了。

用本地 Docker 服务器

需要本地部署时，先在 GitHub 的 Settings → Developer settings → Personal access tokens 生成一个 fine-grained PAT，按需勾选 Contents、Issues、Pull requests 等仓库权限，然后：

claude mcp add github \
  --env GITHUB_PERSONAL_ACCESS_TOKEN=ghp_你的token \
  -- docker run -i --rm \
  -e GITHUB_PERSONAL_ACCESS_TOKEN \
  ghcr.io/github/github-mcp-server

这里 -- 后面是启动 server 的实际命令，-i 保证 stdio 通道打开。MCP 服务器的注册流程和作用域（local / project / user）选择，Claude Code 配置 MCP 服务器完整步骤讲得更细，团队协作建议用 --scope project 写进 .mcp.json 共享。

配置文件长什么样

不管用哪条路径，最终都会落到一份 JSON 配置。桌面版在 claude_desktop_config.json，Claude Code 在 .mcp.json 或用户级配置里。远程服务器的写法如下：

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  }
}

本地 Docker 服务器则是命令式：

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_你的token"
      }
    }
  }
}

改完配置文件后必须完全退出并重启 Claude 桌面版（关窗口不算），新配置才会加载。

权限范围怎么给才安全

MCP 让 Claude 真的能动你的仓库，权限要按最小化原则给：

使用场景建议授予的权限
只查代码 / 读 issue / 看 PRContents 只读、Issues 只读、Pull requests 只读
让 Claude 建 issue / 评论Issues 读写
让 Claude 提交改动 / 开 PRContents 读写、Pull requests 读写

用 fine-grained PAT 时还能把作用域限定到指定仓库，比经典 token 的全账号授权安全得多。涉及配额与计费时具体以 Anthropic 官网和 GitHub 官网为准。

验证连接是否真的能用

配好后别急着上生产，先发一句简单指令试探，比如「帮我看看 octocat/Hello-World 的 README 内容」。如果 Claude 能返回文件正文，说明 get_file_contents 工具链路通了。在 Claude Code 里还可以用 /mcp 命令查看每个服务器暴露了哪些工具、当前授权状态。这一步本质上就是确认 MCP 的工具调用（Tool Use）能正常往返——它和 API 层面的 Claude Tool Use 工具调用怎么用？完整代码实战是同一套机制，只是由 MCP 帮你把工具定义和执行都托管了。

常见问题

连接器一直转圈或显示 connection failed 怎么办？

最常见的三个原因：一是 OAuth 授权没完成（浏览器跳转后没点确认就关了），重新点连接走一遍授权即可；二是本地 Docker 方案下镜像没拉下来或 Docker 没运行，先 docker pull ghcr.io/github/github-mcp-server 确认能拉取；三是改了配置文件但没重启 Claude。Claude Code 用户可以加 --debug 启动看详细日志定位。更系统的排查可参考 Claude Code 报错不工作？常见问题排查清单。

调用 GitHub 工具时报 401 或权限不足？

说明鉴权失败或授权范围不够。远程服务器要确认 OAuth 仍然有效（令牌可能过期，重新授权一次）；本地服务器要检查 GITHUB_PERSONAL_ACCESS_TOKEN 是否填对、PAT 是否过期、所需权限位（如开 PR 需要 Pull requests 读写）是否勾上。注意区分这是 GitHub 侧的鉴权问题，不是 Claude API 的鉴权——后者属于 Claude API 报错 401 怎么解决？认证失败排查指南的范畴。

桌面版连接器和 Claude Code 的 MCP 配置是同一份吗？

不是。桌面版用 claude_desktop_config.json，Claude Code 用 .mcp.json 或 claude mcp add 注册的用户级配置，两者各自独立。你可以只在一处配 GitHub，也可以两处都配；但 OAuth 授权是按客户端分别进行的，在桌面版授权过不等于 Claude Code 也已授权，需要各自走一遍。

← Projects 与 MCP