GitHub MCP Server 如何在 Cursor 中接入远程服务器并用 PAT 认证?

原创2026-09-09 17:44:451,986 阅读
文章标签:MCP 服务人工智能工具调用后端开发工具认证鉴权

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 认证这条路径。

准备条件

  1. Cursor IDE:安装最新版;远程服务器走 Streamable HTTP 传输,Cursor 需为 v0.48.0 或更新版本。
  2. GitHub PAT:在 GitHub 账户的 Personal Access Tokens 设置页创建一个 classic PAT(ghp_ 前缀),并授予你打算使用的操作所需的 scopes。PAT Scope Filtering 说明了 PAT 类型对可见工具的影响,创建 token 前可以先看这一节。
  3. 不需要 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 安装指南 给出的验证顺序检查:

  1. 重启后打开 Settings → Tools & Integrations → MCP Tools,确认 "github" 条目显示绿点(green dot);
  2. 在 chat/composer 中查看 "Available Tools",确认 GitHub 工具已列出;
  3. 直接测试:输入 "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-Toolsets header。

这些配置均为可选,不配置就使用默认工具集,不影响基本的认证流程。

排查常见问题

遇到接入失败时,按 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。

登录后查看全文
github-mcp-server