MCP 实战教程：10 分钟把 GitHub 接进 Cursor，让 AI 自己建 Issue、提 PR（含完整配置与踩坑清单）
先看配完之后你能干什么
这篇是纯实操教程，配完你能直接对 Cursor 说出下面这些话，它自己调 GitHub API 把事情干完：
- 「看下我仓库最近的 issue，把和登录相关的都列出来」——AI 调
list_issues拉取、按关键词过滤，给你一张清单； - 「刚发现分页在第 3 页会白屏，给 repo 建个 issue，打上 bug 标签」——AI 调
create_issue，标题、正文、label 一次写好，去 GitHub 上真的能看到； - 「把这版改动整理成 CHANGELOG，提个 PR 到 main」——AI 读 diff、生成变更日志、调
create_pull_request，PR 链接直接甩给你。
不用改一行 AI 模型代码，不用自己写 API 封装——这正是 MCP 要解决的事。全程 10 分钟，两种接入方式任选，每一步都有验证命令。
一、MCP 是什么：一段人话讲清
MCP（Model Context Protocol，模型上下文协议）是 Anthropic 在 2024 年底开源的标准协议，现在已被 Cursor、VS Code、Claude Desktop、Windsurf 等主流工具支持。你可以把它理解成 AI 界的 USB-C：
- 以前：每个 AI 工具对接每个外部服务，都要写一套专属集成，N 个工具 × M 个服务 = N×M 套代码；
- 有了 MCP：服务方把能力封装成一个 MCP Server（暴露标准协议的小程序），AI 工具方实现一个 MCP Client，两边都按协议说话，N+M 搞定。
对使用者来说只需要记住：我要接 GitHub，就找一个 GitHub MCP Server，填进 AI 工具的配置文件，完事。模型本身不需要任何改动——能力是「插」上去的。
一句话：MCP Server = 给 AI 用的插件，配置文件 = 插座，Cursor = 带 USB-C 口的电脑。
二、前置准备：三样东西，每样都验证
2.1 Docker（方式 B 需要，方式 A 可跳过）
如果你选下面的方式 A（托管版，推荐），不需要 Docker，直接跳到 2.2。选方式 B（本地 Docker 版）的，先确认 Docker 装好并在运行：
docker --version
# 预期输出：Docker version 27.x.x, build xxxxxx
docker run --rm hello-world | head -5
# 预期输出：Hello from Docker! ... 说明 daemon 正常运行macOS/Windows 装 Docker Desktop（Windows 用 WSL2 后端），Linux 用发行版包管理器。第二条报 Cannot connect to the Docker daemon 说明装了但没启动，先把它跑起来。
2.2 GitHub Token：最小权限原则
AI 要替你操作 GitHub，需要一个 Personal Access Token（PAT）。强烈建议用 Fine-grained token，可以精确到「哪个仓库、哪些权限」，泄露了损失也可控：
- GitHub 头像 → Settings → 左侧最底部 Developer settings → Personal access tokens → Fine-grained tokens → Generate new token；
- Repository access 选 Only select repositories，只勾要让 AI 操作的仓库（教程阶段勾一个测试仓库）；
- Permissions → Repository permissions 按需勾最小集合：
| 权限 | 给不给 | 用途 |
|---|---|---|
| Issues: Read and write | ✅ 给 | 建 issue、评论（本教程主场景） |
| Pull requests: Read and write | ✅ 给 | 提 PR（第五节场景） |
| Contents: Read and write | ⚠️ 按需 | 读代码只需 Read；让 AI 提交代码才要 Write |
| Metadata: Read | ✅ 默认 | 必读，自动带上 |
| Administration / Workflows | ❌ 不给 | 教程用不上，给多了是风险 |
- 有效期设 30 或 90 天，别选永不过期；
- 生成后立刻复制——页面一关就再也看不到了。
为什么不推荐 classic PAT：它只有
repo这种大颗粒权限，一个 token 能动你所有仓库的所有内容。Fine-grained 是「钥匙开一把锁」，classic 是「万能钥匙」。
2.3 Cursor 版本
Cursor ≥ 0.48 才支持远程 URL 型 MCP（方式 A 需要）。升级：头像 → Check for Updates。验证入口：Cursor Settings → Tools & MCP，能看到 New MCP Server 按钮就绪。
三、核心步骤：两种接入方式，二选一
配置文件位置（两种方式相同）：
- 项目级（推荐）：项目根目录
.cursor/mcp.json——只对当前项目生效，可以提交进仓库让全组共享； - 全局：
~/.cursor/mcp.json（Windows 是C:\Users\你\.cursor\mcp.json）——所有项目生效。
⚠️ 两者同名时，项目级覆盖全局——排查「明明配了怎么不生效」时先想到这一条。
方式 A：托管版（推荐，零 Docker 依赖）
GitHub 官方托管的远程 MCP Server，HTTPS 直连，本机什么都不用装。Cursor → Settings → Tools & MCP → New MCP Server，会自动创建 .cursor/mcp.json，填入：
{
"mcpServers": {
"github": {
"type": "http",
"url": "https://api.githubcopilot.com/mcp/",
"headers": {
"Authorization": "Bearer ghp_你的PAT"
}
}
}
}说明：
mcpServers是根键，绝对不能漏——漏了不会报错，只是静默不加载，这是第一大坑；type: "http"表示远程传输（老配置里的sse类型仍兼容，新配置统一用http）；- 远程地址就是
https://api.githubcopilot.com/mcp/，GitHub 官方文档给出的公网端点； - 直接配 PAT 的写法如上；如果你的 Cursor 支持 GitHub 账号一键 OAuth 授权，可以省掉 headers 这段，首次连接会弹授权页——两种都行，PAT 写法更可控。
方式 B：Docker 本地版（数据不出本机，可自定义工具集）
GitHub 官方镜像 ghcr.io/github/github-mcp-server 跑在本地容器里，stdout 走 stdio 协议和 Cursor 通信：
{
"mcpServers": {
"github": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"GITHUB_PERSONAL_ACCESS_TOKEN",
"ghcr.io/github/github-mcp-server"
],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_你的PAT"
}
}
}
}逐行解释，这段配置是全文最值得看懂的一块：
command: "docker"——Cursor 启动 MCP Server 时执行的程序；-i——必须有，容器要保持 stdin 打开，Cursor 才能通过 stdio 和它持续对话；--rm——Cursor 退出时容器自动删除，不留垃圾；-e GITHUB_PERSONAL_ACCESS_TOKEN（不带等号）——声明「这个变量的值从宿主环境注入」，真正的值在下面env段；env段——Cursor 会把它注入到启动进程的环境里，容器再透传给应用。
环境变量透传这种写法的好处：token 不出现在 args 命令行里——命令行参数对同机任何用户 ps 一下就能看见，环境变量至少挡住随手一瞥。
选型建议：个人快速上手用方式 A；公司内网、对第三方托管端点敏感、或要通过 GITHUB_HOST 环境变量接 GitHub Enterprise 自建实例的，用方式 B。
配置写完，先别急着用
保存 mcp.json，回到 Cursor Settings → Tools & MCP，应该能看到 github 出现在列表里，右侧开关是绿色状态。红灯？直接跳到「六、踩坑清单」，先排查再往下走。
四、验证三连：一步一确认，绿灯再往下
教程类文章最怕「配完就结束，跑没跑通读者自己猜」。这里按顺序在 Cursor 聊天框（Cmd/Ctrl+L）输入三句，每句都确认结果再继续：
验证 1：连接通不通（只读）
用 GitHub 工具查一下我的账户信息，告诉我登录名预期：AI 调用 get_me，返回你的 GitHub 用户名。
失败：AI 说「找不到工具」→ 服务器没加载，回踩坑清单；说「401/403」→ token 错或过期，回 2.2 重新生成。
验证 2：读操作对不对（只读）
搜索我账号下名字里带 test 的仓库，列出来预期：AI 调 search_repositories，列出你在 2.2 里勾选的仓库。
失败：列表为空 → 检查 Fine-grained token 的 Repository access 是不是没勾这个仓库。
验证 3：写操作真的生效（去 GitHub 眼见为实）
在我的 test 仓库里建一个 issue，标题「MCP 连通性测试」，正文写「由 Cursor + GitHub MCP 创建，可关闭」预期：AI 调 create_issue 返回 issue 链接。别只看聊天窗口——点开链接去 GitHub 页面上确认它真的存在，然后手动关掉它。
这一步过了，说明读写权限、连接、协议三层全通，配置正式完成。
五、实战演练：四个真实场景（prompt 直接抄）
场景 1：整理最近的 issue
列出我 repo 最近两周创建的 issue，按标签分组，标出超过 7 天没人回复的AI 会组合调用 list_issues（带状态、时间参数）和 list_issue_comments 判断活跃度。适合每周站会前快速过一遍。
场景 2：结构化建 issue
帮我建个 issue：标题「移动端 H5 在 iOS 17 下输入框被键盘遮挡」，
正文包含：现象、复现步骤、预期行为、实际行为四段，
标签打 bug 和 mobile，指派给 @你的用户名关键在 prompt 的结构化——把标题、正文分段、label、指派一次说全，AI 就能一次调用完成，不用来回追问。
场景 3：让 AI 分析代码并关联 issue
读一下 src/auth/login.ts，看看 issue #42 描述的越权问题是不是出在这个文件里，
如果是，给出修复思路并在 issue 下评论这是 MCP + 代码库理解（Cursor 的 codebase indexing）的组合拳：read_file 类能力来自 Cursor 本身，get_issue / add_issue_comment 来自 MCP——两个来源的能力在同一个对话里编排。
场景 4：提一个 PR
基于当前分支的改动创建 PR：标题「fix: 修复登录页在 iOS 17 的输入框遮挡」，
描述里列出改动点和测试方式，目标分支 main⚠️ 这一步会真正改动你的仓库。建议：让 AI 先把 PR 标题和描述写给你确认，你说「可以」它再调 create_pull_request——涉及写操作留一个人工确认点，是 AI 编程的基本纪律。
六、踩坑清单：我都替你踩过了
坑 1：配置没生效，还没任何报错
按这个顺序查，90% 的问题在前三步：
- 根键漏了
mcpServers——配置直接写成了{"github": {...}}，正确的是{"mcpServers": {"github": {...}}}。静默失败，无提示； - JSON 语法——尾逗号、注释、单引号都会让解析失败。验证：
cat .cursor/mcp.json | python3 -m json.tool（或贴进任意 JSON 校验器）； - 文件位置错了——必须是
项目根/.cursor/mcp.json，不是cursor/mcp.json，不是家目录； - 没重启 Cursor——改完配置后 Settings → Tools & MCP 里点一次开关，或彻底重启 Cursor。
坑 2：手动跑一遍命令，终端里的报错最诚实
方式 B 的排查金标准——把 Cursor 要执行的命令原样在终端跑：
GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxx \
docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server- 报
Unable to find image后拉取失败 → 网络问题，先docker pull ghcr.io/github/github-mcp-server手动拉（ghcr.io 国内直连可能超时，配镜像加速或走代理）； - 报
bad credentials→ token 复制不完整（常见：漏了首尾字符、复制了空格）； - 命令卡住不退出——这是正常的，它在等 stdio 输入，Ctrl+C 退出即可；
- 终端一切正常、Cursor 里却红灯 → 问题在 Cursor 的 PATH：macOS 的 GUI 应用不读
~/.zshrc，Docker 不在标准路径时把command写成绝对路径"/usr/local/bin/docker"。
坑 3：40 个工具的上限
GitHub MCP Server 会暴露 40+ 个工具（issues、PR、代码、Actions、Projects……），而部分客户端单个 Server 的工具上限是 40——超出会被截断或整个服务器加载失败。解法是只加载用得上的工具集：
"args": ["--toolsets", "repos,issues,pull_requests"]日常三个就够，需要 Actions 再加 actions。工具少还有个附带好处——AI 挑错工具的概率更低、上下文更省。
坑 4：npx 启动的 Server 卡死
网上很多教程的配置长这样："command": "npx", "args": ["some-mcp-server"]，在 Cursor 里表现为「转圈、永远连不上」——因为 npx 没加 -y 时，遇到未安装的包会停在 Ok to proceed? (y) 等你确认，而没人能回答它。改成 ["-y", "some-mcp-server"] 即可。GitHub 官方 Server 走 Docker 或托管端点不涉及这条，但你接其他 Server 时大概率会撞上。
坑 5：SSH 远程开发环境
stdio 型的 MCP Server 必须运行在 AI 客户端进程所在的机器。远程 SSH 场景下客户端在本机、代码在远端，把 Server 配在远端会出现连不上或行为诡异。解法：stdio Server 配在客户端所在机器；远程机器的访问需求用 SSH 反向隧道，或改用托管端点（方式 A 天然免疫这个问题）。
坑 6：Git 用户配置缺失，提 PR 阶段卡住
让 AI 提交 / 提 PR 时，git config 的 user 配置为空会卡住。在项目里确认：
git config user.name # 空的话补上
git config user.email # 空的话补上七、安全红线：PAT 是钥匙，不是装饰
- token 永远不进仓库：
.cursor/mcp.json里填了真实 PAT 的话，把它加进.gitignore（或提交时把 headers/env 段换成占位符让同事自己填）——git log -p能翻出任何已提交的历史，push 前务必检查； - 最小权限 + 最小仓库范围：2.2 的表格照着配，别贪心全勾；
- 定期轮换：Fine-grained token 设置 30/90 天有效期，到期重新生成换上——顺手就做了的安全习惯，比任何工具都有效；
- 怀疑泄露立刻撤销：GitHub → Settings → Developer settings → 对应 token → Revoke，一秒失效；
- 写操作留确认点：建 PR、发评论这类会被别人看见的操作，让 AI 先出草稿你点头再执行。
八、写在最后 + 下一篇预告
回头看，整条链路就三步：拿一个最小权限的 PAT → 写对 mcp.json（记住 mcpServers 根键）→ 一步一验证。MCP 真正的价值不在这 10 分钟的配置，而在于配好之后，AI 从「只会聊代码」变成「能动手干活」——issue、PR、CI 全都成了它的操作对象，而你始终握着权限开关。
下一篇我们把角色反过来：从零写一个自己的 MCP Server——把你自己的内部工具（比如公司的发布系统、监控面板）封装成 MCP 接进 Cursor，stdio 传输、工具定义、调试方法全覆盖。想看的评论区举手。