GitHub MCP Server 如何部署？Windows、Linux、macOS 全平台教程

你在 Cursor 里想让 Agent 直接查 Issue、开 PR、读仓库文件——却卡在「到底该装哪个 GitHub MCP Server」：npm 上的旧包早已弃用，网上教程又各说各话。本文以 GitHub 官方仓库 github/github-mcp-server（截至 2026-07-31 最新 v1.7.0）为准，把远程托管、Docker 本地、预编译二进制、源码编译四条路径写清楚，Windows / Linux / macOS 照抄即可。

交付声明： 本文覆盖 PAT 申请、各平台配置文件路径、Cursor / Claude Desktop / VS Code Copilot 接入示例，以及七步验收清单。不讨论第三方非官方 Server 实现。

---

Quick Answer：四种部署方式怎么选

先对照下表，30 秒内确定你的路径；大多数个人开发者从方式一（远程托管）开始，团队内网或需要凭证隔离时选方式二（Docker）。

部署前准备：PAT、主机应用与配置路径

1. 申请 GitHub Personal Access Token

前往 GitHub → Settings → Personal access tokens 创建 Fine-grained 或 Classic PAT。常用 scope 如下：

• repo — 读写仓库内容、分支、提交
• read:org — 读取组织与团队信息
• 按需追加 read:project、workflow 等（取决于你要让 Agent 操作的范围）

2. MCP 主机应用与配置文件路径

不同客户端的配置文件位置不同。下表按操作系统列出最常见路径——改完 JSON 后通常需要完全重启客户端。注意：部分编辑器会在保存时自动格式化 JSON，若把 PAT 写进 env 字段，确认格式化后引号与逗号仍然合法。

若团队需要隔离的 Mac 环境做 MCP 联调（避免 PAT 落在个人笔记本上），可先租一台 Macstripe 云 Mac 作为专用测试节点，SSH 进去配置 Docker 或二进制，与本机 Cursor 通过 stdio/远程隧道对接。

方式一：远程托管 Server（全平台相同）

GitHub 提供官方远程 MCP 端点：https://api.githubcopilot.com/mcp/。优点是Windows、Linux、macOS 配置完全一致，无需本地跑进程或装 Docker。

认证方式：在 HTTP 请求头中携带 Authorization: Bearer <YOUR_GITHUB_PAT>。各客户端对远程 Server 的 JSON 字段名略有差异，下面给出 Cursor 与 VS Code 的通用写法。

Cursor / VS Code 配置示例

编辑 ~/.cursor/mcp.json（或项目级 .cursor/mcp.json）：

{
  "mcpServers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ghp_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

保存后完全退出并重启 Cursor，在 Settings → MCP 面板确认 github 显示绿色 Connected。首次连接若弹出授权提示，按客户端指引完成即可。

远程托管的优势在于：GitHub 负责 Server 版本升级与安全补丁，你只需维护 PAT 生命周期。对于企业内网环境，若出口 HTTPS 被代理拦截，需在系统或客户端中配置 HTTPS_PROXY，确保能访问 api.githubcopilot.com。测试连通性可在终端执行：

curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer ghp_xxxxxxxxxxxxxxxxxxxx" \
  https://api.githubcopilot.com/mcp/

返回 200 或 405（Method Not Allowed，说明端点可达）即表示网络与 Token 基本正常。若返回 401，检查 PAT 是否过期或 scope 不足。

方式二：Docker 本地部署

官方镜像：ghcr.io/github/github-mcp-server。本地 Docker 适合需要凭证隔离、离线运行或自定义网络策略的团队。镜像支持 PAT 与 OAuth 两种认证模式。

各平台 Docker 前置

• Windows： 安装 Docker Desktop，启用 WSL2 后端，确保 docker version 正常。建议在 Docker Desktop → Settings → Resources 分配至少 2GB 内存，避免容器启动时 OOM。
• macOS： 安装 Docker Desktop for Mac（Apple Silicon 自动拉取 ARM 镜像，无需额外配置）。若使用 Rosetta 转译的 Intel 版 Docker，请确认拉取的是正确架构的镜像层。
• Linux： 安装 Docker Engine（sudo apt install docker.io 或发行版等价包），将用户加入 docker 组后重新登录，否则每次都要 sudo docker。

三种平台的 mcp.json 内容完全相同——这是 Docker 方案相比二进制方案的另一个优势：写一次配置，团队内 Windows / macOS / Linux 开发者直接复用。

PAT 模式 — mcp.json 配置

Docker 通过环境变量 GITHUB_PERSONAL_ACCESS_TOKEN 传入 PAT：

{
  "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_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

OAuth 模式 — 需映射回调端口

若使用 OAuth 流程，需将容器内回调端口映射到本机 127.0.0.1:8085，并设置 GITHUB_OAUTH_CALLBACK_PORT=8085：

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-p", "127.0.0.1:8085:8085",
        "-e", "GITHUB_OAUTH_CALLBACK_PORT=8085",
        "ghcr.io/github/github-mcp-server"
      ]
    }
  }
}

首次连接时浏览器会打开 GitHub 授权页；授权完成后 Token 由 Server 管理，无需在 JSON 里写 PAT。

验证 Docker 镜像可拉取

docker pull ghcr.io/github/github-mcp-server
docker run --rm ghcr.io/github/github-mcp-server --version

若团队把 MCP Server 跑在隔离的远程 Mac 上（例如 Macstripe 云节点），Windows 开发者可通过 SSH 隧道把 stdio 转发到本机 Cursor——既保留 macOS 侧的环境一致性，又不在个人电脑上暴露 PAT。更多 MCP 安全与上线实践可参考 AGNTCon MCP 部署指南。

方式三：预编译二进制

不想装 Docker 时，可从 GitHub Releases 下载对应平台的预编译包（v1.7.0 起）：

macOS / Linux 安装与 PATH

# 以 macOS ARM 为例
tar -xzf github-mcp-server_Darwin_arm64.tar.gz
sudo mv github-mcp-server /usr/local/bin/
chmod +x /usr/local/bin/github-mcp-server
github-mcp-server --version

Windows 安装

# PowerShell
Expand-Archive github-mcp-server_Windows_x86_64.zip -DestinationPath C:\Tools\github-mcp-server
# 将 C:\Tools\github-mcp-server 加入系统 PATH

mcp.json 配置（stdio 模式）

{
  "mcpServers": {
    "github": {
      "command": "github-mcp-server",
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Windows 上若 PATH 未生效，可写绝对路径："command": "C:\\Tools\\github-mcp-server\\github-mcp-server.exe"。

二进制方案的优点是启动快、不依赖 Docker 守护进程；缺点是版本升级需手动下载新 Release 并替换文件。建议团队维护一份内部文档，记录当前使用的版本号（如 v1.7.0）与校验和，避免不同成员跑不同版本的 Server 导致工具行为不一致。

方式四：源码编译（进阶）

需要打自定义分支、贡献 PR 或审计全部源码时，从官方仓库编译。要求 Go 1.24+。

git clone https://github.com/github/github-mcp-server.git
cd github-mcp-server
git checkout v1.7.0   # 或 main
go build -o github-mcp-server ./cmd/github-mcp-server
./github-mcp-server --version

编译产物用法与方式三相同，在 mcp.json 里把 command 指向你编译出的二进制路径即可。生产环境更推荐固定 tag（如 v1.7.0）而非直接跟踪 main。

源码编译适合两类人：一是要给 github/github-mcp-server 提 PR 的贡献者；二是企业安全团队需要审计每一行代码、打内部补丁后再分发二进制。普通开发者若无定制需求，方式一或方式二已足够，不必为此安装 Go 工具链。

接入主流 MCP 主机：Cursor、Claude Desktop、VS Code Copilot

三种客户端的 JSON 结构略有差异，核心都是声明一个 mcpServers 条目。下面汇总最常见写法（以 Docker PAT 模式为例，远程托管只需把 command/args 换成 url + headers）。

Cursor

全局配置 ~/.cursor/mcp.json，项目级用 .cursor/mcp.json。项目级配置适合「只有这个仓库需要 GitHub MCP」的场景——比如开源贡献项目与个人 side project 使用不同的 PAT。重启后在聊天窗口输入「列出我的 GitHub 仓库」验证工具是否可用；若 Agent 回复「我没有 GitHub 工具」，说明 MCP 未正确加载，回到 MCP 面板检查日志。

Claude Desktop

编辑对应平台的 claude_desktop_config.json，结构与 Cursor 相同，顶层键也是 mcpServers：

{
  "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_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

保存后退出 Claude Desktop 再打开。macOS 用户可在菜单栏图标 → Settings → Developer 查看 MCP 连接日志。

VS Code Copilot（Agent 模式）

在 VS Code 1.99+ 中，Copilot Chat 支持 MCP。打开 Command Palette → MCP: Add Server，或在工作区创建 .vscode/mcp.json。远程托管写法与 Cursor 完全一致。

不确定该用 Cursor 还是 Claude Code？可参考 AI 编程工具选购对比，再决定 MCP 主机。

七步验收清单与常见故障排查

配置完成后，按下面清单逐项打勾，确保 Agent 能真正调用 GitHub 工具。

• Step 1： PAT 已创建且 scope 包含 repo（及所需的 read:org 等）
• Step 2： mcp.json JSON 语法合法（可用 jq . 或在线校验器检查）
• Step 3： 客户端已完全重启（不是只关窗口）
• Step 4： MCP 面板显示 github 为 Connected / 绿色
• Step 5： 对话中执行「列出我的 GitHub 仓库」能返回真实仓库名
• Step 6： 尝试读取某个私有仓库文件，确认 PAT 权限足够
• Step 7： 检查客户端日志无 401 Unauthorized 或 connection refused

常见故障排查表

旧认知：「装个 npm 包就能连 GitHub。」
2025 年 4 月起官方路线是 github/github-mcp-server；远程托管则连 api.githubcopilot.com/mcp/，不要再搜 server-github。

常见问题

远程托管和 Docker 本地部署该怎么选？

个人尝鲜或团队快速验证，优先选 GitHub 远程托管（https://api.githubcopilot.com/mcp/），全平台配置相同、无需维护进程。需要离线运行、自定义工具集或严格凭证隔离时，选 Docker 本地部署（ghcr.io/github/github-mcp-server）。

还能用 npm 的 @modelcontextprotocol/server-github 吗？

不能。该 npm 包已于 2025 年 4 月弃用，请改用 GitHub 官方仓库 github/github-mcp-server（当前最新 v1.7.0）。

PAT 需要哪些权限范围？

Fine-grained 或 Classic PAT 至少包含 repo（读写仓库）与 read:org（读取组织信息）。若需操作 Issues、Pull Requests 或 Projects，按实际工具调用范围追加对应 scope。

Windows 上 Docker 拉镜像失败怎么办？

确认 Docker Desktop 已启动且 WSL2 后端正常；在 Settings → Resources 给 Docker 分配足够内存；执行 docker login ghcr.io 后重试 docker pull ghcr.io/github/github-mcp-server。

Cursor 改了 mcp.json 不生效怎么办？

保存 JSON 后完全退出 Cursor 再重启；检查 ~/.cursor/mcp.json 与项目 .cursor/mcp.json 是否冲突（项目级优先）；在 Settings → MCP 面板查看连接状态与错误日志。

总结

GitHub MCP Server 的官方部署路线已经很清晰：

1. 最快上手 — 远程托管 https://api.githubcopilot.com/mcp/ + PAT，全平台同一套 JSON
2. 本地可控 — Docker 镜像 ghcr.io/github/github-mcp-server，PAT 或 OAuth 二选一
3. 无 Docker — Releases 下载预编译二进制，配好 PATH 即可
4. 进阶定制 — Go 1.24+ 源码编译，固定 tag 上线

建议先用远程托管在 Cursor 里跑通「列仓库 → 读文件 → 查 Issue」三步，确认 PAT 权限无误后，再决定是否迁到 Docker 或远程 Mac 隔离环境。

对于团队场景，推荐把 MCP 配置文件（去掉 PAT 明文后）纳入版本管理，用环境变量或密钥管理服务注入 Token——这与 MCP 安全部署最佳实践一致。Windows 开发者若同时要 iOS 构建与 Agent 工作流，Macstripe 云 Mac 可按天租用专用节点，约 5 分钟开通 SSH，把 MCP Server、Xcode 与 Fastlane 放在同一台 macOS 上，笔记本只当远程终端——比在个人电脑上混跑 Docker + Xcode 远程插件稳定得多。

延伸阅读

• AGNTCon MCPCon Europe 2026 MCP 部署指南 →
• Claude Code vs Cursor vs Codex：AI 编程工具选购 2026 →
• 开发者租 Mac 跑 AI Agent：云 Mac 实战 2026 →