GitHub MCP Server 使用指南 - API 安装配置教程

什么是 GitHub MCP Server

GitHub MCP Server（@modelcontextprotocol/server-github）是面向 GitHub 官方 API 的 MCP 实现。它把「查仓库、改 Issue、开 PR、搜代码、动分支」等操作封装成模型可调用的工具，使你在Claude Desktop、Cursor 等客户端里用自然语言完成一部分原本要在网页或 gh CLI 里点的流程。与本地 Filesystem MCP 互补：前者管远端托管与协作，后者管你磁盘上的工作副本。

使用前必须在环境中提供GITHUB_TOKEN（个人访问令牌或 Fine-grained PAT），否则无法通过 GitHub API 鉴权。更多 MCP 可在 MCP 服务器目录检索；需要拼出完整多服务配置时，可用 MCP 配置生成器。

核心功能一览

仓库管理

读取仓库信息、文件树与元数据，辅助代码审阅与文档对齐。

Issue / PR

列出、创建或更新 Issue 和 Pull Request，减轻在 UI 间切换的成本。

代码搜索

在组织或仓库范围内检索符号与片段，配合对话解释结果。

分支管理

查看与操作分支相关能力（以当前工具集为准），支持工作流自动化思路。

文件操作

通过 API 读取或提交远端文件变更路径，与本地 Git 流程配合使用。

安装与配置

创建 GitHub Token

登录 GitHub →Settings →Developer settings →Personal access tokens，创建经典 token 或 Fine-grained token。最小权限原则：只勾选当前工作需要的 scope（如 repo、read:org 等），切勿把 token 提交到仓库或截图外传。

设置环境变量

在启动 MCP 的同一环境中导出令牌（示例为类 Unix shell）：

export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

Windows PowerShell 可使用$env:GITHUB_TOKEN="ghp_..."；Claude Desktop 等平台通常支持在配置里为进程注入 env 字段（见下文）。

安全：GITHUB_TOKEN 等同于你的账户能力子集。若泄露，他人可能读写你有权访问的私有仓库。轮换 token、撤销旧令牌，并避免在日志中打印环境变量。

安装命令

npx -y @modelcontextprotocol/server-github

确保运行该命令时进程已能读取 GITHUB_TOKEN。

Claude Desktop 配置示例（含 token）

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_你的令牌请从环境迁移勿硬编码提交"
      }
    }
  }
}

建议：不要把真实 token 长期写在共享配置文件中。可改为由系统环境变量提供，并在 JSON 里不写明文（若客户端支持从父进程继承环境，则只配置 command/args 即可）。具体以 Claude Desktop 当前版本文档为准。

Cursor 配置示例

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "在此填写 PAT，或改为在系统中设置同名环境变量后省略 env"
      }
    }
  }
}

推荐在操作系统用户级环境中持久化 GITHUB_TOKEN，配置里只保留command 和 args，由 Cursor 启动子进程时自动继承变量，避免明文落盘。

典型使用场景

跨仓库调查：让模型根据 Issue 列表和 PR 描述总结发布阻塞点。
开源贡献：在对话中定位 good first issue，并拉取相关文件上下文。
团队运维：批量检索某错误关键词在组织内的出现位置。
与本地联调：本地 Filesystem 改代码+ GitHub MCP 开 PR，形成闭环（仍需你本地 git push）。

配置示例小结

三要素：npx -y @modelcontextprotocol/server-github、可用的 Node 环境、有效的 GITHUB_TOKEN。多机器同步时，优先用操作系统密钥管理器注入 token，而不是把密钥同步到网盘。完整模板可从 MCP 配置生成器生成后再合并进现有 mcpServers。

常见问题

403 或鉴权失败？

检查 token 是否过期、scope 是否包含目标操作、组织是否开启 SSO 授权（需对 token 做 SSO approve）。

能改私有仓库吗？

取决于 token 权限；Fine-grained token 还需显式勾选仓库访问列表。

和gh CLI 有什么区别？

GitHub MCP 面向「模型工具调用」协议；CLI 面向人类终端。二者可并存，按场景选用。

🐙 GitHub API MCP Server 使用指南