企业官网建设流程全解析

1. Cursor 1.0 里 GitHub MCP 到底解决什么问题

如果你最近在 Cursor 1.0 里翻设置，大概率会看到一个新面板叫 MCP Tools，旁边还跟着 Background Agent 和 Privacy Mode 两个开关。很多人第一反应是「这又是个新功能，先放着」，但真正用起来之后你会发现，GitHub MCP 解决的是一个很具体的痛点：让 AI 直接操作你的 GitHub 仓库，而不是只在你本地文件里打转。

先说清楚它是什么。MCP 全称 Model Context Protocol，你可以把它理解成 AI 和外部工具之间的「标准插座」。GitHub MCP 就是 GitHub 官方提供的那个插座，插上之后，Cursor 里的 AI 能读 issue、拉 PR、查 commit、建分支、提 review comment，甚至根据 issue 描述直接生成改动。它不是一个独立的 App，而是跑在 Docker 容器里的一个服务，Cursor 负责调度它。

能做什么，我列几个我实际跑通的场景：让 AI 读某个 issue 的完整讨论然后给出实现方案；让 AI 对比两个分支的 diff 并总结变更点；让 AI 根据 PR 里的 review comment 自动改代码；让 AI 在 Background Agent 里跑一个「修完这个 bug 就提 PR」的闭环。这些操作以前要么手动切浏览器，要么复制粘贴一堆上下文，现在在 Cursor 里一句话就能触发。

适合谁？三类人最值得花时间配：一是每天要处理多个 PR 的 reviewer，二是维护开源项目、issue 堆积如山的 maintainer，三是想把「读 issue → 改代码 → 提 PR」串成自动流的独立开发者。如果你只是偶尔写写小脚本，本地 AI 补全够用了，MCP 的收益没那么明显。

但这里有个前提，也是最多人卡住的地方：GitHub MCP 依赖 Docker 跑容器，而 Cursor 出于权限考虑不会帮你启动 Docker。所以整个落地路径其实是「先保证 Docker 活着 → 再开 Background Agent → 再配 MCP Server → 最后验证请求」。顺序错了，就会看到各种连接失败。下面我按这个顺序拆开讲，每一步都给可复制的配置和验证动作。

另外提一句，MCP Server 本身只负责「连 GitHub」，它不负责模型推理。模型这块你可以用 Cursor 自带的，也可以接第三方兼容 OpenAI 协议的服务。我实测下来，把模型侧配成 TaoToken 的 API 端点，再配合 GitHub MCP 做工具调用，整个链路是通的，后面 §3 会给完整的配置片段。

2. Docker 环境准备与 Background Agent 启用踩坑记录

这一节是整篇最容易翻车的地方，我见过太多人卡在「Enable Background Agent 是灰的」或者「Cannot connect to the Docker daemon」。先把这两个问题的根因说透。

2.1 Docker Desktop 必须先手动启动

GitHub MCP Server 的官方镜像跑在容器里，Cursor 在启用 MCP Server 时会自动执行类似docker run -i --rm ...的命令。注意，是 Cursor 自动执行，但它不会帮你启动 Docker 引擎本身。macOS 上你要点开 Docker Desktop，等状态栏图标变成稳定的运行态；Windows 上确认 Docker Desktop 的鲸鱼图标不再转圈；Linux 上确认systemctl status docker是 active。

验证 Docker 是否就绪，终端跑一条：

docker info --format '{{.ServerVersion}}'

能打印出版本号就说明 daemon 在跑。如果报Cannot connect to the Docker daemon at unix:///var/run/docker.sock，那就是引擎没起，跟 Cursor 无关，先把 Docker 弄活。

我踩过的坑是：Mac 合盖休眠后 Docker 会自己停，第二天打开 Cursor 发现 MCP 全红。后来在 Docker Desktop 设置里勾了「Start Docker Desktop when you sign in」，省心很多。

2.2 Privacy Mode 会挡住 Background Agent

Background Agent 是 Cursor 的远程/云端代理能力，MCP Tools 的调度依赖它。如果你发现设置里 Background Agent 的开关点不动，或者点了又弹回去，九成是 Privacy Mode 开着。

操作路径：Settings 顶部搜索框输入privacy，找到 Privacy Mode 开关，关掉。关完建议重启一次 Cursor，让配置生效。重启后再回 Background Agent 面板，开关应该能正常切到开启状态。

这里要理解两者的关系：Background Agent 是基础设施，MCP Tools 是跑在它上面的应用。基础设施没开，应用面板里添加 MCP Server 的按钮就是灰的。所以顺序永远是「关 Privacy Mode → 开 Background Agent → 配 MCP Server」。

2.3 一键安装与 OAuth 认证

Cursor 1.0 支持一键安装官方 MCP Server，也支持 OAuth 认证。你可以在 MCP Tools 面板里找 GitHub 的条目，点安装，然后走 OAuth 授权流程，浏览器会弹出 GitHub 的授权页，确认后 token 就存好了。这条路最省事，适合不想碰配置文件的人。

但如果你要精细控制，比如指定 PAT、指定镜像版本、或者把配置纳入版本控制，就得手写 JSON。下一节给完整骨架。

2.4 模型侧的前置准备

MCP 负责工具调用，模型负责推理。如果你想让整条链路稳定，模型端点最好也配好。我这边用的是 TaoToken 的兼容端点，Base URL 填https://taotoken.net/api，Key 在控制台生成。这一步不是 GitHub MCP 的硬性要求，但配好之后，工具调用和模型推理走同一套配置，排障时变量更少。

生成 Key 的入口在控制台的 API Keys 页面，创建后复制出来，注意只显示一次。模型 ID 按你实际要用的填，比如claude-sonnet-4-20250514这类。三件套（Base URL + Key + Model ID）在 §3 的配置里会一起出现。

3. 可复制的 MCP 配置骨架与三件套写法

这一节给能直接抄的配置。分两块：一块是 Cursor 侧的 MCP Server 定义，一块是模型侧的三件套。两块都配好，链路才完整。

3.1 Cursor 的 mcp.json 配置

Cursor 的 MCP 配置放在项目根目录的.cursor/mcp.json，或者全局配置里。推荐放项目级，方便跟仓库一起管理。骨架如下：

{ "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，args里-i保持标准输入打开，--rm让容器退出后自动清理，-e把环境变量透传进容器。镜像地址是ghcr.io/github/github-mcp-server，这是 GitHub 官方维护的。

PAT 的权限别给太大。去 GitHub Settings → Developer settings → Personal access tokens 建一个 fine-grained token，只勾你需要的仓库和权限，比如Contents: Read and write、Pull requests: Read and write、Issues: Read and write。给全权限的 classic token 一旦泄露风险很大。

3.2 把 Token 从版本控制里摘出去

如果你要把.cursor/mcp.json提交到仓库，千万别把 PAT 写死在里面。做法是在 mcp.json 里只引用环境变量名，实际值放在本地不提交的文件里。上面那段env里的值，可以改成从系统环境变量读：

{ "mcpServers": { "github": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server" ], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${env:GITHUB_PAT}" } } } }

然后在你的 shell 配置里export GITHUB_PAT=ghp_xxx。这样 mcp.json 可以安全提交，token 留在本地。

3.3 模型侧三件套

模型侧的三件套是 Base URL、Key、Model ID。如果你用 TaoToken 的兼容端点，配置长这样：

{ "baseUrl": "https://taotoken.net/api", "apiKey": "sk-你的Key", "model": "claude-sonnet-4-20250514" }

Base URL 用https://taotoken.net/api，不要加多余的路径。Key 在控制台的 API Keys 页面生成。Model ID 按你实际要用的模型填。这三件套在 Cursor 的模型设置里对应填进去，或者在支持自定义端点的客户端里配。

3.4 配置校验

配完别急着用，先做静态校验。JSON 文件用jq过一遍：

jq . .cursor/mcp.json

能正常输出格式化结果就说明语法没问题。然后确认 Docker 镜像能拉下来：

docker pull ghcr.io/github/github-mcp-server

这一步能成功，说明网络和镜像源都通。如果卡在拉取，多半是网络问题，跟 Cursor 无关。

4. 验证请求与成功结果长什么样

配置写完，怎么确认它真的在工作？这一节给几个可观察的信号。

4.1 MCP Tools 面板的状态

打开 Cursor 设置 → MCP Tools，你应该能看到github这个 server 条目，状态是绿色或者显示 connected。如果显示红色或者一直转圈，点开看错误信息。常见的是Cannot connect to the Docker daemon，回到 §2.1 检查 Docker。

4.2 用一条真实请求验证

在 MCP Tools 面板里选中 github server，找到专属输入入口（有的版本是 Ask 按钮，有的是右键菜单的 Send to MCP）。输入一条最简单的请求，比如：

列出当前仓库最近 5 个 commit 的标题

如果链路通，几秒内会返回 commit 列表。这一步验证的是「Cursor → Docker 容器 → GitHub API」整条链路。

注意一个高频误区：不要在普通的 AI 聊天对话框里输入 MCP 请求。那个对话框只由本地 AI 处理，不会转发到 MCP Server。必须走 MCP Tools 的专属入口，结果才会由 MCP Server 返回。

4.3 验证模型侧是否生效

如果你想确认模型侧三件套也通了，可以在 Cursor 的模型对话里发一条普通请求，看是否正常返回。或者用 curl 直接打端点：

curl https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer sk-你的Key" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-sonnet-4-20250514", "messages": [{"role": "user", "content": "ping"}] }'

返回里有choices字段就说明模型侧通了。这一步和 MCP 是独立的，分开验证能快速定位问题在哪一侧。

4.4 一个完整的闭环示例

验证通过后，试一个完整闭环：让 AI 读一个 issue，生成改动，然后提 PR。在 MCP Tools 输入：

读取 issue #12 的内容，根据描述在 src/ 下生成对应改动，并创建一个新分支提交

成功的话，你会看到 AI 先调 GitHub MCP 读 issue，再在本地生成代码，最后调 MCP 建分支和提交。整个过程在 Cursor 里完成，不用切浏览器。这就是 Background Agent + GitHub MCP 组合起来的价值。

5. 常见报错排查对照表

这一节按真实报错来，每条给现象、原因、动作。

5.1 Cannot connect to the Docker daemon

现象：MCP Tools 面板里 github server 显示红色，点开提示连不上 Docker daemon。

原因：Docker 引擎没启动，或者当前用户没权限访问 socket。

动作：先跑docker info确认引擎状态。Linux 上如果报权限错误，把当前用户加进 docker 组：sudo usermod -aG docker $USER，然后重新登录。Mac/Windows 上确认 Docker Desktop 在运行。

5.2 401 Unauthorized

现象：MCP 请求返回 401，或者 GitHub API 报未授权。

原因：PAT 无效、过期、或者权限不够。

动作：去 GitHub 重新生成 fine-grained token，确认勾了目标仓库和所需权限。检查 mcp.json 里的环境变量名和实际 export 的变量名是否一致，大小写敏感。

5.3 local proxy failed

现象：请求发出后报local proxy failed或类似连接错误。

原因：通常是本地网络层的问题，比如端口被占、代理配置冲突。

动作：检查是否有其他进程占用 Docker 的端口。如果你本地配了 HTTP 代理，确认 Docker 的代理设置和它一致。Docker Desktop 的设置里有 Proxies 一栏，填对。

5.4 reading choices 报错

现象：模型侧返回error reading choices或解析失败。

原因：模型端点返回的 JSON 结构不符合预期，或者 Base URL 填错。

动作：确认 Base URL 是https://taotoken.net/api，不要多加/v1之外的路径。用 §4.3 的 curl 单独测模型端点，看返回结构。如果 curl 正常但 Cursor 里报错，检查 Cursor 的模型配置里 Base URL 是否被自动补了路径。

5.5 OAuth 授权卡住

现象：点一键安装后，浏览器授权页打不开，或者授权完 Cursor 没反应。

原因：OAuth 回调被拦截，或者浏览器和 Cursor 的会话不同步。

动作：换默认浏览器重试，确认没有插件拦截回调。如果还是不行，改用手写 mcp.json + PAT 的方式，绕过 OAuth。

5.6 Background Agent 开关灰掉

现象：Background Agent 开关点不动。

原因：Privacy Mode 开着。

动作：Settings 搜 privacy，关掉 Privacy Mode，重启 Cursor。这是 §2.2 讲过的，但报错时人容易忘，单独列一条。

5.7 容器启动后立刻退出

现象：MCP server 状态闪一下红色，日志显示容器退出。

原因：镜像版本不匹配，或者环境变量没传进去。

动作：手动跑一次docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxx ghcr.io/github/github-mcp-server，看终端输出。如果报缺 token，说明 env 没传对；如果报镜像找不到，docker pull一下确认镜像名。

6. 把 GitHub MCP 接进日常编码流

配好只是开始，真正省时间的是把它嵌进日常动作里。

我自己的用法是：早上打开 Cursor，先让 MCP 拉一遍昨天 assign 给我的 issue 和待 review 的 PR，列个清单。然后挑一个 issue，让 AI 读完整讨论生成实现方案，我确认后让它建分支改代码。改完再让 MCP 提 PR，附上从 issue 里提取的上下文。整个流程里我基本不切浏览器。

团队协作场景下，MCP 生成的 PR 描述和 review comment 回复质量比手写稳定，因为它能直接读到 issue 和 diff 的完整上下文。代码审查时，让 MCP 对比两个分支的 diff 并标出风险点，比人肉翻文件快很多。

如果你要把这套流跑顺，模型侧建议用稳定的端点。TaoToken 的 API 端点https://taotoken.net/api配合 GitHub MCP 做工具调用，我实测下来延迟和稳定性都够用。Key 在控制台生成，模型 ID 按需选。想先试试模型对话效果的，可以从模型对话入口进；要长期跑编码和 Agent 任务的，看 Coding Plan；接入文档和 API Keys 分别在文档页和控制台。

最后留一个实用技巧：把常用的 MCP 请求存成 Cursor 的 snippet 或者命令面板里的自定义命令，比如「读 issue 生成方案」「对比分支 diff」「根据 review 改代码」。下次一句话触发，不用每次重新描述。这套配下来，GitHub MCP 才算真正变成你工作流的一部分，而不是设置里一个吃灰的开关。