GitHub MCP Server (Official)

什么是 GitHub MCP Server (Official)？

GitHub MCP server 是 GitHub 官方的 Model Context Protocol 服务器，让 AI 智能体能够通过自然语言读取仓库和代码、管理 issue 与 pull request、查看 GitHub Actions 运行情况并检查安全告警。它既可以作为 GitHub 托管的远程服务器使用，也可以在本地通过 Docker 运行。

该项目由 GitHub 在开源仓库 github/github-mcp-server 中维护，采用 MIT 许可证。托管端点为 https://api.githubcopilot.com/mcp/；本地版本以公开镜像 ghcr.io/github/github-mcp-server 和发布版二进制文件的形式提供。

如何使用 GitHub MCP Server (Official)？

两种模式任选其一：

• 远程（由 GitHub 托管）：需要支持远程服务器的 MCP 宿主（README 列出了 VS Code 1.101+、Claude Desktop、Cursor、Windsurf 等），并启用所有适用的组织策略。
• 本地：需要安装并运行 Docker，或者使用 go build 构建、从 releases 页面下载的二进制文件。

认证方式为 GitHub OAuth（浏览器流程；令牌只保存在内存中）或在 GITHUB_PERSONAL_ACCESS_TOKEN 中提供 GitHub Personal Access Token（PAT），后者优先于 OAuth。可在 github.com/settings/personal-access-tokens/new 创建令牌，并且只授予所需的权限范围。

Claude Code

远程服务器（Claude Code 2.1.1 及更新版本），在终端中运行：

claude mcp add-json github '{"type":"http","url":"https://api.githubcopilot.com/mcp","headers":{"Authorization":"Bearer YOUR_GITHUB_PAT"}}'

使用 Docker 和 PAT 的本地服务器：

claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=YOUR_GITHUB_PAT -- docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server

重启 Claude Code，然后运行 claude mcp list 确认服务器已配置。

Claude Desktop

GitHub 的指南说明，Claude Desktop 的自定义连接器目前不支持远程服务器所需的 OAuth 流程，因此请在 claude_desktop_config.json 中使用本地 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": "YOUR_GITHUB_PAT"
      }
    }
  }
}

Cursor

Cursor v0.48.0+ 可以使用托管服务器。将以下内容添加到 ~/.cursor/mcp.json（或项目中的 .cursor/mcp.json），然后重启 Cursor：

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

VS Code

使用 README 中的一键安装按钮，或手动添加远程服务器（VS Code 1.101+ 会自动处理 OAuth），然后在 Copilot Chat 中切换到 Agent 模式：

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

Codex

编辑 ~/.codex/config.toml：

[mcp_servers.github]
url = "https://api.githubcopilot.com/mcp/"
bearer_token_env_var = "GITHUB_PAT_TOKEN"

官方还提供了 Copilot CLI、JetBrains、Visual Studio、Eclipse、Xcode、Windsurf、Zed、OpenCode、Gemini CLI 和 Rovo Dev CLI 的安装指南。

GitHub MCP Server (Official) 的主要功能

• GitHub 官方项目，提供托管的远程服务器，以及本地 Docker 或二进制文件两种方式。
• 支持 OAuth 登录或 Personal Access Token 认证。
• 工具集（toolsets）：通过 --toolsets 或 GITHUB_TOOLSETS 只启用需要的功能组（默认：context、repos、issues、pull_requests、users；all 启用全部）。
• 通过 --tools / GITHUB_TOOLS 单独选择工具，可单独使用，也可与工具集组合。
• 只读模式（--read-only 或 GITHUB_READ_ONLY=1）只暴露读取类工具。
• 锁定模式（--lockdown-mode）会过滤公开仓库中没有推送权限的作者所写的内容，以降低提示注入风险。
• 通过 --gh-host / GITHUB_HOST 支持 GitHub Enterprise Server 和 ghe.com。
• Insiders 模式可提前体验实验性工具。

GitHub MCP Server (Official) 工具

工具按照 GitHub 产品领域划分为多个工具集：

• 上下文与用户：get_me、get_teams 和 search_users 让智能体了解自己以哪个身份操作。GitHub 称 context 工具集为“强烈推荐”。
• 仓库与 Git：使用 get_file_contents、search_code、list_commits、create_branch、create_or_update_file、push_files、fork_repository 和 get_repository_tree 浏览和修改代码。
• Issue 与 pull request：list_issues、issue_read、issue_write、search_issues、create_pull_request、pull_request_read、pull_request_review_write 和 merge_pull_request 覆盖分类、评审和合并。
• Actions：actions_list、actions_get、actions_run_trigger 和 get_job_logs 用于查看和触发工作流运行。
• 安全：代码扫描、Dependabot、密钥扫描和安全公告相关工具，例如 list_code_scanning_alerts 和 list_dependabot_alerts。
• 协作：discussions、通知、projects、gists、标签、stargazers 和组织相关工具。
• 仅远程提供：create_pull_request_with_copilot（Copilot coding agent）、Copilot Spaces 和 github_support_docs_search。

GitHub MCP Server (Official) 的使用场景

• 代码探索：“找到这个仓库里限流器的实现位置，并解释它的工作原理。”
• Issue 分类：“列出上周标记为 bug 的未关闭 issue，并汇总其中的重复项。”
• Pull request 评审：“读取 PR 42 的 diff，标出有风险的改动并留下评审意见。”
• CI 调试：“main 分支上最近一次工作流运行为什么失败？显示失败任务的日志。”
• 安全审查：“按严重程度列出这个仓库中未处理的 Dependabot 和代码扫描告警。”
• 委派任务：在远程服务器上，让 Copilot coding agent 针对描述的任务创建 pull request。

GitHub MCP Server (Official) 与替代方案对比

• 官方版与早期社区版、参考实现：MCP servers 仓库中较早的 GitHub 参考服务器（Github MCP Server）和 npm 包 @modelcontextprotocol/server-github 已不再受支持；GitHub 文档引导用户改用 ghcr.io/github/github-mcp-server。cyanheads/github-mcp-server 等社区项目也已弃用，转而推荐官方服务器。
• 远程与本地：远程服务器无需 Docker，并提供额外的工具集；本地服务器适用于不支持远程 MCP 的宿主以及 GitHub Enterprise Server。
• 其他代码托管平台：如果代码托管在 GitLab，请参阅 GitLab MCP Server。

GitHub MCP Server (Official) 常见问题排查

• Docker 镜像拉取失败：该镜像是公开的；过期的令牌可能导致拉取失败，请运行 docker logout ghcr.io 后重试。
• Cursor 中无法连接远程服务器：确认 Cursor 版本为 v0.48.0 或更高（支持 Streamable HTTP），并确认 PAT 有效且权限范围正确。
• claude mcp add-json 返回 “Invalid input”（Windows 上有报告）：改用旧版命令 claude mcp add --transport http github https://api.githubcopilot.com/mcp -H "Authorization: Bearer YOUR_GITHUB_PAT"。
• 设置 --tools 后服务器启动失败：工具名必须完全匹配（例如 get_file_contents）；无效名称会导致服务器无法启动。
• 写入类工具缺失：只读模式会跳过写入类工具，即使你在 --tools 中列出了它们。