一句话总结：通过自定义 MCP 服务把 Notion AI 变成你电脑的"远程操作员"，让它直接读写本地文件、跑命令、调用本地 Claude Code（cc）和 Codex（cx）完成复杂编码任务。
本文记录从领取 Notion 商业版试用到真正打通本地链路的完整过程，包括我踩过的所有坑。
这篇文章解决什么问题
如果你像我一样，是个想把 Notion AI 用得更深的小白，可能有过这种想法：
- Notion AI 只能改 Notion 页面，能不能让它直接改我电脑里的代码？
- 我本地装了 Claude Code、Codex CLI，能不能让 Notion AI 当"调度员"，把任务派给它们？
- 大模型的算力能不能延伸到我的本地开发环境？
答案是：可以，而且不难。但中间会踩一些坑，特别是国内网络环境下。这篇文章把全流程和踩坑经验都记录下来。
整体方案与原理
角色分工
- Notion AI：在云端，负责"思考"和"指挥"
- Cloudflared：把你电脑的本地端口开成公网 HTTPS 入口（Notion 在云端，无法直接访问 127.0.0.1）
- 本地 MCP 服务：项目的核心，提供文件、Shell、Git、任务委派等工具
- cc / cx：真正干重活的本地大模型 CLI
为什么需要这个方案
直接的 Notion AI 只能在 Notion 工作区里活动。MCP（Model Context Protocol） 是个开放协议，允许 AI 通过它"远程调用"任意工具。我们用的开源项目
catoncat/notion-local-ops-mcp 把本地的"超能力"用 MCP 协议暴露出来，Notion AI 就能像调用自己的工具一样调用它们。第一步：领取 Notion 商业版试用
自定义 MCP 服务需要 Notion 商业版（Business）或更高方案才能配置。
操作流程
- 打开 Notion 工作区设置 → Plans / 计划
- 找到 Business 计划 → 点击 Start free trial / 开始免费试用
- 通常有 14 天免费试用期，足够你跑通整套流程
- 试用期间所有商业版能力都开放，包括自定义 MCP Agent
注意：试用期结束如果不续费，自定义 MCP 配置会失效。如果只是想体验一下流程，14 天足够。如果想长期用，需要付费。
第二步：准备本地环境
必装清单
工具 | 作用 | 安装方式（macOS） |
Python 3.11+ | 跑 MCP 服务 | brew install python@3.11 |
cloudflared | 公网隧道 | brew install cloudflared |
git | 拉项目代码 | macOS 自带或 brew install git |
Claude Code (cc) | 本地 Claude CLI | 参考 Anthropic 官方文档安装 |
Codex CLI (cx) | 本地 Codex CLI | 参考 OpenAI 官方文档安装 |
cc 和 cx 至少装一个就行，否则delegate_task（任务委派）功能用不了。但基础的文件、Shell、Git 操作不受影响。
拉项目并配置
编辑
.env 文件，至少改这两行：WORKSPACE_ROOT：MCP 服务的"沙箱根目录"，Notion AI 只能在这里读写。建议设成你装项目的父目录（比如~/projects或~/githubProject），后面切换子项目时无需重启服务。
AUTH_TOKEN：相当于"门钥匙"，待会儿要填到 Notion 里。
第三步：一键启动
这个脚本一口气帮你做完所有事：
- ✅ 创建 Python 虚拟环境
.venv（首次约 2-5 分钟，之后秒级复用）
- ✅ 安装所有依赖
- ✅ 启动本地 MCP 服务（
http://127.0.0.1:8766/mcp）
- ✅ 启动 cloudflared 隧道，分配公网 HTTPS 地址
成功的标志，是日志里同时出现这两行：
以及一个公网地址：
这个公网 URL 每次重启脚本都会变（快速隧道特性），要在 Notion 里更新配置。想固定 URL 要用 Named Tunnel。
第四步：踩坑实录（重要！）
这一节是我整个过程中最折腾的部分，国内网络环境下大概率会遇到。
坑 1：Cloudflare Error 1033 / 530
现象：
curl 公网地址返回 530，Notion 报"SSE 错误：非 200 状态码 (530)"。根因排查：
如果本地都正常，但公网 530，几乎可以确定是隧道注册失败。
坑 2：QUIC/UDP 被网络屏蔽
现象：cloudflared 日志里反复出现：
并且始终没有
Registered tunnel connection。原因：Cloudflare 默认走 QUIC 协议（UDP 7844/443），国内很多网络（公司、校园、运营商策略）会限制 UDP 出站。
解决：强制走 HTTP/2（基于 TCP 443，跟普通 HTTPS 一样）。
直接编辑
scripts/dev-tunnel.sh，找到这一行：改成：
重启脚本后日志应该出现：
坑 3：DNS 污染
现象：日志里出现：
原因：国内某些运营商 DNS（如示例中的中国移动 DNS）对 Cloudflare 相关域名有污染，直接返回"无此域名"。
解决：把系统 DNS 改成公共 DNS。
操作：系统设置 → 网络 → 当前网络 → 详细信息 → DNS，添加：
把
1.1.1.1 拖到最上面优先用。验证：终极兜底方案：换工具
如果你的网络对 Cloudflare 整体不友好，可以换 ngrok：
拿到
https://xxxx.ngrok-free.app 地址，加 /mcp 后填到 Notion 就能用。第五步：在 Notion 里配置 MCP Agent
创建自定义 Agent
- Notion → Agents → 新建自定义 Agent
- 给它起个名字，比如
本地操作员
- 进入 Agent 设置 → 找到 MCP 连接 配置
填入连接信息
字段 | 值 |
URL | https://你的隧道域名.trycloudflare.com/mcp ← 末尾必须加 /mcp |
Auth type | Bearer |
Token | .env 里设的 NOTION_LOCAL_OPS_AUTH_TOKEN |
粘贴推荐的 Agent Prompt
项目 README 里有一段官方推荐的系统提示词（Recommended MCP Agent prompt），把它整段粘贴到 Agent 的指令里。这段提示词会让 Agent：
- 优先用直接工具（文件、Shell、Git）
- 复杂任务才委派给 cc / cx
- 自动跟踪进度、做最小验证、写 commit
第六步：测试连接
在 Notion 里和这个 Agent 对话，依次试这几条：
列出当前工作目录的文件→ 测文件读取
运行 pwd 和 git status→ 测 Shell 和 Git
把当前工作目录切到 ~/projects/some-project→ 测set_default_cwd
用 codex 帮我实现一个 Python 脚本，把当前目录的图片批量改名→ 测delegate_task
如果都能正常执行，恭喜你，全链路打通了。
进阶：让一切更省心
1. 多项目切换
把
WORKSPACE_ROOT 设成项目大目录（如 ~/projects），然后在 Notion 对话里直接说："切到 proj-B 这个项目，跑测试"。Agent 会自动调 set_default_cwd，无需重启服务。2. 后台常驻（不用一直开终端）
会装两个 macOS LaunchAgent，开机自启 + 自动重启。常用命令：
3. 固定公网 URL（Named Tunnel）
在 Cloudflare 后台建一个命名隧道，绑定你的子域名，URL 永久不变，重启也不用改 Notion 配置。
之后跑
./scripts/dev-tunnel.sh 会自动检测并优先使用命名隧道。我的踩坑总结
给后来者的几条经验：
/mcp后缀必加——80% 的"连不上"是这个原因
- 公网 URL 每次会变——快速隧道的代价，长期用上 Named Tunnel
- 国内网络优先 HTTP/2 + 1.1.1.1 DNS——能省很多调试时间
WORKSPACE_ROOT设宽一点——避免反复重启切项目
- "进程在跑"≠"隧道注册成功"——必须在日志里看到
Registered tunnel connection
- 修改
.env必须完整重启，不能用滚动重载（reload不会重读环境变量）
最终效果
配置完成后，我可以在 Notion 里直接说：
- "看一下
~/projects/my-app的 git 状态，把没提交的改动总结成 commit"
- "用 cc 帮我重构
src/utils.py里的parse_config函数，加上类型注解"
- "跑一下测试，如果失败把错误贴出来分析"
Notion AI 会自己规划步骤、调用本地工具、必要时委派给 cc/cx、最后总结结果。整个体验非常接近一个"远程开发助理"。
参考资源
- Cloudflare Tunnel 文档：https://developers.cloudflare.com/cloudflare-one/connections/connect-apps
- MCP 协议官方介绍：https://modelcontextprotocol.io
