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

GitHub MCP Server 是 GitHub 官方维护的 Model Context Protocol 服务端，让 Cursor、Claude Desktop、VS Code Copilot 等 AI 宿主能通过标准化工具调用 GitHub REST / GraphQL API——查仓库、读 Issue、开 PR、搜代码，不必在聊天里反复粘贴 gh 命令输出。

本文按「先选型、再装环境、最后接入 IDE」的顺序，覆盖 Windows、Linux、macOS 三条安装路径，并附上可直接复制的配置片段与排障清单。

2025 年 4 月起，社区早期的 npm 包 @modelcontextprotocol/server-github 已废弃；当前唯一受官方支持的本地镜像为 ghcr.io/github/github-mcp-server，远程托管端点为 https://api.githubcopilot.com/mcp/。

部署方式怎么选

在动手装软件之前，先对照下面这张表，确定自己要走哪条路：

三种方式认证逻辑相同：要么配置 Personal Access Token（PAT），要么在本地 Docker / 二进制模式下走 OAuth 浏览器登录（token 仅驻留内存，不落盘）。

通用前置准备

无论选哪条路径，建议先完成下面四步：

1. 创建 GitHub PAT
   打开 Fine-grained PAT 创建页，按你要用的工具勾选权限。只读浏览仓库通常需要 Contents: Read、Metadata: Read；若要创建 PR / Issue，再追加写权限。

2. 确认宿主版本
   - Cursor：v0.48.0+ 才支持远程 Streamable HTTP
   - Claude Desktop / VS Code：参考各自 MCP 文档

3. （本地 Docker 方案）安装并启动 Docker
   - Windows / macOS：Docker Desktop
   - Linux：Docker Engine + 将当前用户加入 docker 组

4. 预拉镜像（可选但推荐）

docker pull ghcr.io/github/github-mcp-server

若拉取报 unauthorized，执行 docker logout ghcr.io 后重试——有时是过期的 ghcr 登录态在捣乱。

方式一：远程托管（最省事）

GitHub 在 https://api.githubcopilot.com/mcp/ 提供托管 MCP 端点，本机无需 Docker。适合 Linux 服务器、Windows 轻量环境，或公司策略禁止跑容器的情况。

Cursor 配置示例

编辑全局配置 ~/.cursor/mcp.json（Windows 路径为 %USERPROFILE%\.cursor\mcp.json）：

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

将 YOUR_GITHUB_PAT 替换为真实 token，保存后完全重启 Cursor。在 Settings → Tools & Integrations → MCP Tools 中应看到绿色在线指示；在 Composer 里问一句「列出我的 GitHub 仓库」即可验收。

注意事项

• 远程模式目前以 PAT 认证为主；部分宿主对 OAuth 的支持仍在完善中。
• 公司代理 / 防火墙需放行对 api.githubcopilot.com 的 HTTPS 出站。
• 不要把 PAT 写进版本库；项目级配置用 .cursor/mcp.json 时记得加入 .gitignore。

方式二：Docker 本地部署（官方推荐）

Docker 方案通过 stdio 与宿主通信：宿主启动 docker run -i ...，容器内进程读写标准输入输出。这也是 Claude Desktop、Windsurf、Cursor 一键安装按钮背后的默认命令。

macOS 安装步骤

1. 安装 Docker Desktop for Mac（Apple Silicon 选 ARM64 版）。
2. 菜单栏鲸鱼图标显示 Running。
3. 终端验证：

docker run --rm ghcr.io/github/github-mcp-server --help

4. 写入 ~/.cursor/mcp.json：

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

Linux 安装步骤

1. 按发行版安装 Docker Engine（Ubuntu 示例：sudo apt install docker.io）。
2. 将用户加入 docker 组，避免每次 sudo：

sudo usermod -aG docker "$USER"
newgrp docker

3. 确保 Docker 守护进程已启动：sudo systemctl enable --now docker。
4. MCP 配置与 macOS 完全相同——~/.cursor/mcp.json 路径一致。

在 无图形界面的 Linux 服务器上，若不想在配置里明文写 PAT，可改用环境变量注入：

export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_xxxx"

然后在 mcp.json 的 env 块里引用同名变量（部分宿主支持 ${env:GITHUB_PERSONAL_ACCESS_TOKEN} 语法，以宿主文档为准）。

Windows 安装步骤

1. 安装 Docker Desktop for Windows。
   - 推荐 WSL 2 后端（Settings → General → Use WSL 2 based engine）。
2. 确认 Docker Desktop 托盘图标为运行状态。
3. 配置文件路径：%USERPROFILE%\.cursor\mcp.json。
4. JSON 内容与 macOS 一致；command 仍为 docker（Docker Desktop 会把 CLI 加入 PATH）。

常见 Windows 坑：WSL 里能跑 docker，但 Windows 宿主 Cursor 读的是 Windows 侧 mcp.json——两边配置不要混用。若 Cursor 装在 Windows、项目在 WSL，优先在 Windows 用户目录 配 MCP。

OAuth 登录（免手写 PAT）

官方镜像内置 OAuth 应用凭据。Docker 模式下需把回调端口映射到本机回环地址：

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

首次连接会弹出浏览器完成 GitHub 登录；token 保存在内存，容器退出即失效。无头服务器可查阅官方文档的 device code 回退流程。

方式三：Go 源码编译（无 Docker）

适合无法安装 Docker、或需要裁剪 toolset（只暴露部分 API 能力）的场景。

三平台共同步骤

前置：安装 Go 1.24+。

git clone https://github.com/github/github-mcp-server.git
cd github-mcp-server
go build -o github-mcp-server cmd/github-mcp-server/main.go

编译产物命名可自定；下文以 ./github-mcp-server 为例。

用 PAT 启动（stdio 模式）：

export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_xxxx"
./github-mcp-server stdio

Cursor 接入本地二进制：

{
  "mcpServers": {
    "github": {
      "command": "/绝对路径/github-mcp-server",
      "args": ["stdio"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT"
      }
    }
  }
}

升级时重新 git pull && go build 即可；不必等 Docker 镜像发版。

接入其他 IDE 与 CLI

配置键名因宿主而异，但 Docker 命令行核心一致：

docker run -i --rm \
  -e GITHUB_PERSONAL_ACCESS_TOKEN \
  ghcr.io/github/github-mcp-server

• Claude Desktop：claude_desktop_config.json 里的 mcpServers 块，结构与 Cursor 相同。
• VS Code Copilot：支持远程 + 本地；本地同样推荐 Docker 镜像。
• Claude Code CLI：倾向轻量二进制方案，减少容器开销。

各宿主完整示例见官方仓库 docs/installation-guides/ 目录。

安全与运维建议

1. 最小权限 PAT：按 toolset 开权限，定期轮换。
2. 配置文件权限：chmod 600 ~/.cursor/mcp.json（Linux / macOS）。
3. 只读模式：启动参数可启用 read-only，防止 AI 误改仓库。
4. 企业 GitHub Enterprise Server：需自建 OAuth App / GitHub App，不能使用 github.com 默认 OAuth 凭据——详见官方 docs/oauth-login.md。

平台差异补充说明

路径与环境变量

~/.cursor/mcp.json

macOS 与 Linux 的全局 MCP 配置；Windows 对应 %USERPROFILE%\.cursor\mcp.json。

GITHUB_PERSONAL_ACCESS_TOKEN

Docker / 二进制模式下的 PAT 环境变量名；设置后优先级高于 OAuth 流程。

GITHUB_OAUTH_CALLBACK_PORT

OAuth 浏览器回调监听端口，Docker 场景通常固定为 8085。

快捷键与习惯用法

在 Cursor Composer 中，可用 Cmd+Shift+P（Windows 为 Ctrl+Shift+P）打开命令面板，搜索 MCP 相关设置。早期有人习惯用 npx @modelcontextprotocol/server-github 一行命令拉起服务——该方式已废弃，请改用本文的 Docker 或远程端点方案。

生产环境务必把 PAT 放在环境变量或密钥管理器里，不要写进会被 git 跟踪的项目文件。

验证清单（发布前）

1. MCP 面板绿点
2. 工具列表出现 github_* 前缀项
3. 试调用只读操作（如列仓库）成功

日志位置提示

Cursor 日志可在 Help → Toggle Developer Tools → Console 中过滤 MCP 关键字查看；Claude Desktop 日志路径因平台而异，官方 troubleshooting 章节有完整列表。

故障排查速查

本地快速自检：在终端手动跑 Docker 命令，看 stderr 是否立即报错；再对比 IDE 日志里的 MCP 启动命令是否一致。

小结

• 想最快用上：远程 https://api.githubcopilot.com/mcp/ + PAT，Cursor v0.48+ 直接配 url。
• 想稳定可复现：三平台统一 docker run -i --rm ... ghcr.io/github/github-mcp-server。
• 想极致轻量或定制：go build 出二进制，stdio 接入。

部署完成后，在 AI 对话里用自然语言操作 GitHub——例如「给 kvmkit 仓库最近 5 个 open issue 做个摘要」——才是 MCP 真正省时间的地方。若你同时在搭建 CI/CD 流水线 或需要 7×24 云端 Mac 构建节点，可以把 MCP 辅助开发与自动化发布放在同一套工具链里统筹规划。

常见问题