GitHub MCP 服务器配置

在 Cursor / Windsurf 等客户端接入官方 GitHub MCP（Remote 或 Docker），用 Agent 查询仓库、Issue 与 PR。

概述

Model Context Protocol（MCP）让 IDE 里的 Agent 调用外部工具。官方 github/github-mcp-server 可查询仓库、Issue、PR 等。本篇以 Cursor 为主，并注明 Windsurf 差异。

Install MCP Server

重要：npm 包 @modelcontextprotocol/server-github 自 2025 年 4 月起已废弃且不可用。请使用 GitHub 托管 Remote，或 Docker 镜像 ghcr.io/github/github-mcp-server。

前置条件

支持 MCP 的客户端（Cursor v0.48+ 推荐；Windsurf 等）
GitHub PAT（最小必要 scope，如 repo）
若走本地 Docker：Docker Desktop 已运行

安装与获取

推荐：Cursor Remote（Streamable HTTP）

编辑全局 ~/.cursor/mcp.json 或项目 .cursor/mcp.json：

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

将 YOUR_GITHUB_PAT 换成真实令牌，保存后完全重启 Cursor。也可使用官方文档中的一键安装 Deeplink。详见 Install in Cursor。

本地：Docker + PAT

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

Windsurf

在 Cascade 中通过插件市场安装 GitHub MCP，或编辑 ~/.codeium/windsurf/mcp_config.json，配置同样优先官方 Docker / Remote，不要再写废弃的 npx npm 包。指南：Install in Windsurf。

首次配置

Settings → Tools & MCP（Cursor）确认 github 显示为可用（绿点）
在 Chat / Agent 的 Available Tools 中看到 GitHub 相关工具
试一句：「列出我有权限的仓库」或「总结当前仓库的 open issues」

核心用法

查 PR / Issue，再让 Agent 在本地改代码对应修复
对比分支、阅读评审意见后实现修改
与项目 Rules 结合：约定「先列 issue 再动代码」

示例：

用 GitHub MCP 打开 issue #42 的正文，在本仓库实现修复并补测试；不要直接 push。

开发实践

PAT 放本机配置或密钥管理，永不提交到 Git
企业仓库用最小 scope；定期轮换令牌
Agent 提出的远程写操作（建 issue、评论）默认先人工确认
本地 Docker 拉镜像失败时可 docker logout ghcr.io 后重试

常见问题

Remote 连不上：确认 Cursor ≥ 0.48；检查代理/防火墙
认证失败：PAT scope 与是否过期
工具列表为空：JSON 是否合法；是否已重启客户端
仍在用 npx npm 包：改为 Remote 或 ghcr.io/github/github-mcp-server