notion-local-ops-mcp

将 Notion AI 与你的本地文件、shell 和备用本地代理结合使用。

📖 项目介绍 (Notion 页面)

提供功能

• list_files

• search_files

• read_file

• replace_in_file

• write_file

• run_command

• delegate_task

• get_task

• cancel_task

delegate_task 支持本地 codex 和 claude CLI。

要求

• Python 3.11+

• cloudflared

• 带有自定义 MCP 支持的 Notion 自定义代理

• 可选：codex CLI

• 可选：claude CLI

安装

git clone https://github.com/<your-account>/notion-local-ops-mcp.git
cd notion-local-ops-mcp

python3.11 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -e .

配置

复制 .env.example 并至少设置以下内容：

export NOTION_LOCAL_OPS_WORKSPACE_ROOT="/absolute/path/to/workspace"
export NOTION_LOCAL_OPS_AUTH_TOKEN="replace-me"

可选：

export NOTION_LOCAL_OPS_CODEX_COMMAND="codex"
export NOTION_LOCAL_OPS_CLAUDE_COMMAND="claude"
export NOTION_LOCAL_OPS_COMMAND_TIMEOUT="30"
export NOTION_LOCAL_OPS_DELEGATE_TIMEOUT="1800"

启动

source .venv/bin/activate
notion-local-ops-mcp

本地端点：

http://127.0.0.1:8766/mcp

使用 cloudflared 暴露服务

快速隧道

cloudflared tunnel --url http://127.0.0.1:8766

将生成的 HTTPS URL 与 /mcp 一起使用。

命名隧道

编辑 cloudflared-example.yml，然后运行：

cloudflared tunnel --config ./cloudflared-example.yml run <your-tunnel-name>

添加到 Notion

使用：

• URL: https://<your-domain-or-tunnel>/mcp

• 认证类型: Bearer

• 令牌: 你的 NOTION_LOCAL_OPS_AUTH_TOKEN

推荐的代理指令：

Use direct tools first: list_files, search_files, read_file, replace_in_file, write_file, run_command.
Use delegate_task only for complex multi-file work, long-running tasks, or when direct tools are insufficient.

环境变量

工具说明

• list_files: 列出文件和目录

• search_files: 在文件中搜索文本

• read_file: 读取带有偏移量和限制的文本文件

• replace_in_file: 替换一个精确的文本片段

• write_file: 写入完整的文件内容

• run_command: 运行本地 shell 命令

• delegate_task: 将任务发送到本地 codex 或 claude

• get_task: 读取任务状态和输出尾部

• cancel_task: 停止已委托的任务

验证

source .venv/bin/activate
pytest -q
python -m compileall src tests

故障排除

Notion 显示无法连接

• 检查 URL 是否以 /mcp 结尾

• 检查认证类型是否为 Bearer

• 检查令牌是否与 NOTION_LOCAL_OPS_AUTH_TOKEN 匹配

• 检查 cloudflared 是否仍在运行

SSE 路径在本地有效但在隧道上无效

• 使用命名隧道而不是快速隧道重试

• 确认 GET /mcp 返回 text/event-stream

delegate_task 失败

• 检查 codex --help

• 检查 claude --help

• 如有必要，设置 NOTION_LOCAL_OPS_CODEX_COMMAND 或 NOTION_LOCAL_OPS_CLAUDE_COMMAND