平台通知

全屏浏览 VibeHub

全屏浏览,获得更沉浸的体验。你可以随时通过菜单退出全屏。

社区技巧
工作流入门通用

让 AI 自己搭好 Notion 云端的本地手脚:MCP + Cloudflare 隧道 + 随开随关

把这篇发给你的 AI Agent,它会照步骤装好 MCP 服务、建 Cloudflare 隧道、在 Notion 里注册连接,并做成打开 Notion 自动起服务、关闭自动全停——不用手挂后台窗口。Notion 桌面版(咸鱼上可以花20块钱买三个月的商业版会员,有opus5.5、6.1sol、grok4.6、k3、glm5.3以及deepseek等) + Cloudflare 账号(免费版即可)+ 自有域名

由 notbesttime 分享2026年10月18日

用法:把本文全文发给你的 AI Agent(Claude Code / Codex / DSH 等),它可照着逐步执行。 每步都带验证命令和失败判据;卡住时对照「坑」小节处理。 目标环境:Windows 10/11 + Notion 桌面版 + Cloudflare 账号(免费版即可)+ 自有域名。

给执行者(AI)的约定

  • 每完成一步先跑该步的验证,通过后再进下一步;失败不要跳过。
  • 路径与域名用占位符替换:<插件目录>、<工作区根>、<你的域名>。
  • 不要向用户索取 Notion 密码或 Cookie;MCP 用现场生成的 Bearer token。
  • 全程不需要用户手动开窗口:最终做成「开 Notion 自动起服务、关 Notion 自动全停」。

第 0 步:先确认账号支持(不通过就停止)

让用户在 Notion 里打开:设置 → 连接 → 「+ 添加连接」下拉,确认有没有 「自定义 MCP 连接」。

结果动作
有继续第 1 步
只有第三方 SaaS 列表停止,报告「账号不支持自定义 MCP」
被管理员禁用停止,无绕过方案

注意:设置里的 「Notion MCP」页是反方向(让别人读你的 Notion),别在那里找入口。

第 1 步:部署 MCP 服务端

cd <插件目录>
git clone https://github.com/catoncat/notion-local-ops-mcp.git
cd notion-local-ops-mcp
uv venv .venv --python 3.12
$env:UV_DEFAULT_INDEX = "https://pypi.tuna.tsinghua.edu.cn/simple"
uv pip install -e . --python .venv\Scripts\python.exe

写 .env(token 现场随机生成,别用默认值):

NOTION_LOCAL_OPS_HOST=127.0.0.1
NOTION_LOCAL_OPS_PORT=8766
NOTION_LOCAL_OPS_WORKSPACE_ROOT=<工作区根>
NOTION_LOCAL_OPS_STATE_DIR=<插件目录>/.state
NOTION_LOCAL_OPS_AUTH_TOKEN=<随机长串>
NOTION_LOCAL_OPS_DELEGATE_TIMEOUT=1800

验证:

.venv\Scripts\python.exe -m notion_local_ops_mcp.server
# 期望 Uvicorn running on http://127.0.0.1:8766

Invoke-WebRequest http://127.0.0.1:8766/mcp -UseBasicParsing
# 期望 401
Invoke-WebRequest http://127.0.0.1:8766/mcp -Headers @{Authorization="Bearer <token>"}
# 期望 200

第 2 步:建 Cloudflare 隧道

隧道只能网页创建,API 建不了。让用户操作:

https://one.dash.cloudflare.com
→ 网络 → 隧道 → 创建隧道 → Cloudflared → 命名 notion-mcp → 保存
→ 复制 eyJ 开头的 tunnel token

装并启动:

winget install --id Cloudflare.cloudflared
cloudflared.exe tunnel --no-autoupdate run --token <eyJ...>
# 期望 4 条 Registered tunnel connection ... protocol=quic

配路由(网页):隧道详情 → 路由 → 添加路由 → 已发布的应用程序

  • 子域 notion-mcp,域选你的域名
  • 目标 URL 必须是 http://127.0.0.1:8766

验证:

Invoke-WebRequest https://notion-mcp.<你的域名>/mcp -UseBasicParsing
# 401 = 通了;530 = 隧道进程没跑;1033/502 = 路由配错

第 3 步:在 Notion 注册连接

设置 → 连接 → + 添加连接 → 自定义 MCP 连接
  URL    https://notion-mcp.<你的域名>/mcp     ← 结尾必须带 /mcp
  Auth   Bearer
  Token  <NOTION_LOCAL_OPS_AUTH_TOKEN>

保存后 Connected 列表出现绿色对勾。然后新建 MCP Agent 并填入以下指令(别省,否则模型会回「我是沙箱」):

你是连接到我本机电脑的助手,通过 MCP 操作本地文件。
规则:
- 上下文出现本地路径、文件名、代码扩展名时,把"文件""文档"理解成本地文件,不要当成 Notion 页面
- 编辑本地文件用 apply_patch,不要用 <edit_reference>(那是改 Notion 页面的)
- 用户说"改""修复""实现""部署"时直接执行,不要只给计划就问要不要做
- 回答代码问题给文件路径、行号,不要用 Notion 引用脚注
- 缺失信息靠工具查,不要反问用户
- 多步复杂任务用 delegate_task 交给本地 codex

验证:让 Agent 执行 列出 <工作区根> 目录下的文件,能看到真实目录内容即通。

第 4 步:让服务随 Notion 启停

Notion 桌面版是 Electron,用 CDP 注入要带调试端口;但它是单实例,已有实例会吃掉参数,所以必须先杀干净。

启动器要点(launch.mjs):

// 1) 幂等:端口/进程已在就不重复起
function portInUse(port, timeoutMs = 800) {
  return new Promise((resolve) => {
    const s = new net.Socket();
    const done = (v) => { try { s.destroy(); } catch {} resolve(v); };
    s.setTimeout(timeoutMs);
    s.once('connect', () => done(true));
    s.once('timeout', () => done(false));
    s.once('error',  () => done(false));
    s.connect(port, '127.0.0.1');
  });
}

// 2) 起 MCP:必须给真实管道,stdio:'ignore' 会让 uvicorn 崩溃
mcpProc = spawn(MCP_PY, ['-m', 'notion_local_ops_mcp.server'], {
  cwd: MCP_DIR, env: Object.assign({}, process.env, loadEnvFile(MCP_DIR + '/.env')),
  windowsHide: true,
  stdio: ['ignore', fs.openSync(log, 'a'), fs.openSync(log, 'a')],
});

// 3) 关闭联动
process.on('exit', () => {
  stopChild(cfProc, 'cloudflared');
  stopChild(mcpProc, 'MCP');
});

无窗口启动(launch.vbs):sh.Run """node"" ""launch.mjs""", 0, False 快捷方式指向 wscript.exe "launch.vbs",图标沿用 Notion 原图标。

验证:

  • 双击快捷方式 → Notion、9222、8766、cloudflared 全部出现
  • 关闭 Notion → 12 秒后四者全部退出

11 个必踩的坑

  1. WORKSPACE_ROOT 不是沙箱。只是相对路径锚点,Agent 理论上能访问整个磁盘。
  2. API Token 建不了隧道。cfut_ 开头的不行,必须用 eyJ 的 tunnel token。
  3. 新版「公共主机名」改叫「已发布的应用程序」,藏在「路由」里。
  4. URL 必须带 /mcp 结尾,只填域名连不上。
  5. 别用 getAIUsageEligibility 判断额度。它返回遗留字段(spaceLimit:50),Business 账号会算出 1602% 的假数字。真实额度只有 getCreditRateLimitStatus 有。
  6. spaceId 不是每页都有。/blank、/quick-search 没有,必须做多级回退(URL 参数 → UUID 正则 → localStorage 缓存)。
  7. Notion 单实例。已有实例会静默吃掉 --remote-debugging-port,表现为「开了但 9222 连不上」。先 taskkill /F /T /IM Notion.exe。
  8. stdio:'ignore' 让 Python 秒退(code=4294967295)。必须重定向到日志文件。
  9. MCP 不自己读 .env。直接 spawn python 时环境变量是空的,要在启动器里解析合并,否则 401 全拒。
  10. PowerShell 5 读 UTF-8 中文路径乱码。含中文路径的脚本存成 UTF-8 with BOM。
  11. 桌面会留两个同名 Notion 快捷方式,图标一样极易点错,建议备份后删原版。

验收清单

MCP 本地       http://127.0.0.1:8766/mcp            401
MCP 带鉴权     加 Authorization: Bearer            200
公网链路       https://notion-mcp.<域名>/mcp        200
工具目录       list_tools()                        24 个
真实执行       run_command echo OK                 stdout=OK
Notion 连接    设置 → 连接 → Connected             绿勾
端到端         让 Agent 列目录                      真实内容
启停联动       关 Notion 后 12 秒                   四进程全退

已知限制

  • 多步工具任务不稳:轻量模型较稳;大模型做 3 步以上连续工具调用时,偶尔出现「收到工具结果后只思考不回答」并中断。建议:复杂任务用 delegate_task 转发给本地 codex / claude 执行,让 Notion 只当调度层。
  • 单次 token / 首字延迟抓不到:桌面版推理走 Electron 主进程,不经过渲染层网络栈,CDP 够不着。只能用额度增量估算。
  • 每轮上下文很重:Notion Agent 自带约 78 个内置工具 + 18 个电脑操作工具,容易干扰工具选择。

参考