GitHub MCP Server 如何在 Cursor 中接入远程服务器并用 PAT 认证?
GitHub MCP Server 如何在 Cursor 中接入远程服务器并用 PAT 认证?
如果你想在 Cursor 中调用 GitHub MCP Server 的工具(查询仓库、Issue、Pull Request 等),官方推荐的接入方式是使用 GitHub 托管的远程服务器,而不是在本地跑 Docker。这条路径不需要安装 Docker 或构建 Go 二进制,只需要两样东西:一个最新版 Cursor(远程 Streamable HTTP 支持要求 Cursor v0.48.0 及以上),和一个带有合适 scopes 的 GitHub Personal Access Token(PAT)。接入完成后,你在 Cursor 的聊天或 composer 里就能直接使用 GitHub 相关工具。
需要说明一点:Cursor 虽然支持 OAuth 认证部分 MCP 服务器,但 GitHub 托管的 MCP 服务器目前要求使用 PAT,本文只覆盖 PAT 认证这条路径。
准备条件
- Cursor IDE:安装最新版;远程服务器走 Streamable HTTP 传输,Cursor 需为 v0.48.0 或更新版本。
- GitHub PAT:在 GitHub 账户的 Personal Access Tokens 设置页创建一个 classic PAT(
ghp_前缀),并授予你打算使用的操作所需的 scopes。PAT Scope Filtering 说明了 PAT 类型对可见工具的影响,创建 token 前可以先看这一节。 - 不需要 Docker 或本地运行时——这是远程接入与本地接入的区别。本地 Docker 方案在 Cursor 安装指南 中有单独的配置示例,属于另一条路径,本文不展开。
配置远程服务器
编辑 Cursor 的全局 MCP 配置文件 ~/.cursor/mcp.json(如果想只对某个项目生效,可以在项目根目录使用 .cursor/mcp.json),写入:
{
"mcpServers": {
"github": {
"url": "https://api.githubcopilot.com/mcp/",
"headers": {
"Authorization": "Bearer YOUR_GITHUB_PAT"
}
}
}
}
url固定为 GitHub 托管的远程服务器地址https://api.githubcopilot.com/mcp/。YOUR_GITHUB_PAT是占位符,替换为你创建的实际 PAT 值。
也可以走图形化流程:在 Cursor 的 Tools & Integrations > MCP tools 中找到 "github" 项,点击旁边的铅笔图标编辑,把 YOUR_GITHUB_PAT 换成真实 token,保存文件。
保存配置后完全重启 Cursor(不是重新加载窗口,文档要求 complete restart)。
验证接入结果
按 Cursor 安装指南 给出的验证顺序检查:
- 重启后打开 Settings → Tools & Integrations → MCP Tools,确认 "github" 条目显示绿点(green dot);
- 在 chat/composer 中查看 "Available Tools",确认 GitHub 工具已列出;
- 直接测试:输入 "List my GitHub repositories",能返回你的仓库列表即说明认证和工具调用都正常。
PAT scopes 与可见工具
远程服务器对 PAT 认证有一个重要行为:它会根据 classic PAT 的 OAuth scopes 自动过滤工具。启动时服务器向 GitHub API 发一个轻量 HEAD 请求,从 X-OAuth-Scopes 响应头读取 token 的 scopes,缺少对应 scope 的工具会被直接隐藏。也就是说,如果你的 PAT 只有 repo 和 gist,需要 admin:org、project、notifications 的工具不会出现。
不同 token 类型的差异(见 PAT Scope Filtering):
| Token 类型 | 工具可见性 |
|---|---|
Classic PAT(ghp_) |
按 scopes 过滤,缺少 scope 的工具被隐藏 |
Fine-grained PAT(github_pat_) |
不过滤,全部工具可见,由 GitHub API 在执行时强制权限 |
| GitHub App / 服务端 token | 不过滤,权限按 app 配置执行 |
注意 scopes 存在隐含包含关系:repo 隐含 public_repo、security_events;admin:org 隐含 write:org 再隐含 read:org。另外,只操作公开仓库的只读工具(如 get_file_contents)始终可见,即使 token 没有 repo scope。
配置 token 时可以用下面的命令确认它实际携带的 scopes($GITHUB_PERSONAL_ACCESS_TOKEN 需先设为你的 PAT):
curl -sI -H "Authorization: Bearer $GITHUB_PERSONAL_ACCESS_TOKEN" \
https://api.github.com/user | grep -i x-oauth-scopes
文档给出的示例输出:
x-oauth-scopes: delete_repo, gist, read:org, repo
如果你之后在 GitHub 的 token 设置页调整了 scopes,需要重启 MCP 服务器使变更生效。
可选:用 header 限制工具集
默认配置下远程服务器使用 default toolsets。如果只想暴露部分能力,可以在 headers 里加限制项,配置方式与本地服务器的 flag/env 一一对应(见 Server Configuration Guide 和 Remote Server):
{
"mcpServers": {
"github": {
"url": "https://api.githubcopilot.com/mcp/x/issues/readonly",
"headers": {
"Authorization": "Bearer YOUR_GITHUB_PAT",
"X-MCP-Toolsets": "repos,issues"
}
}
}
}
可用的控制手段:
X-MCP-Toolsets:逗号分隔的工具集列表(如"repos,issues");X-MCP-Tools:逗号分隔的单个工具列表,无效工具名会导致服务器拒绝启动;X-MCP-Readonly:只启用读工具;read-only 是优先于其他配置的严格过滤,即使显式添加了写工具也会被禁用;- URL 路径修饰符:在 URL 末尾加
/readonly启用只读,用/x/{toolset}指定单个工具集,例如https://api.githubcopilot.com/mcp/x/issues/readonly。注意路径里的{toolset}只能写一个工具集,要组合多个请用X-MCP-Toolsetsheader。
这些配置均为可选,不配置就使用默认工具集,不影响基本的认证流程。
排查常见问题
遇到接入失败时,按 Cursor 安装指南 的排查清单逐项核对:
- Streamable HTTP 不生效:确认 Cursor 版本是 v0.48.0 或更新,旧版本不支持该传输;
- 认证失败:核对 PAT 的 scopes 是否覆盖你要用的工具(classic PAT 下 scopes 不足的工具会被隐藏,而不是报错);缺少预期工具时到 GitHub 的 token 设置页补 scopes,然后重启;
- 连接错误:检查防火墙和代理设置,远程服务器依赖访问
api.githubcopilot.com; - 配置后 MCP 一直不加载:确认是完全重启了 Cursor,且
mcp.json的 JSON 格式合法(多余逗号、缺引号都会导致整个文件不生效); - 工具不出现:回到 MCP Tools 页面确认服务器是绿点状态,并在 Cursor 日志中查找 MCP 相关的错误。
另外,安装指南 README 的支持矩阵显示 Cursor 对远程服务器的支持形态是 "✅ PAT + ❌ No OAuth",即 OAuth 流程在 Cursor 中不可用,遇到要求走 OAuth 的教程内容可以忽略,以 PAT 配置为准。
下一步
接入验证通过后,如果默认工具集不够用,可以按 Server Configuration Guide 的工具集/单工具示例进一步收窄或扩展;如果想了解远程服务器独有的工具(例如 create_pull_request_with_copilot),见 Remote Server。