notion-local-ops-mcp

Use Notion AI with your local files, shell, and fallback local agents.

📖 Project Introduction (Notion Page)

What It Provides

• list_files

• search_files

• read_file

• replace_in_file

• write_file

• run_command

• delegate_task

• get_task

• cancel_task

delegate_task supports local codex and claude CLIs.

Requirements

• Python 3.11+

• cloudflared

• Notion Custom Agent with custom MCP support

• Optional: codex CLI

• Optional: claude CLI

Install

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 .

Configure

Copy .env.example and set at least:

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

Optional:

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"

Start

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

Local endpoint:

http://127.0.0.1:8766/mcp

Expose With cloudflared

Quick tunnel

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

Use the generated HTTPS URL with /mcp.

Named tunnel

Edit cloudflared-example.yml, then run:

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

Add To Notion

Use:

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

• Auth type: Bearer

• Token: your NOTION_LOCAL_OPS_AUTH_TOKEN

Recommended agent instruction:

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.

Environment Variables

Tool Notes

• list_files: list files and directories

• search_files: search text in files

• read_file: read text files with offset and limit

• replace_in_file: replace one exact text fragment

• write_file: write full file content

• run_command: run local shell commands

• delegate_task: send a task to local codex or claude

• get_task: read task status and output tail

• cancel_task: stop a delegated task

Verify

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

Troubleshooting

Notion says it cannot connect

• Check the URL ends with /mcp

• Check the auth type is Bearer

• Check the token matches NOTION_LOCAL_OPS_AUTH_TOKEN

• Check cloudflared is still running

SSE path works locally but not over tunnel

• Retry with a named tunnel instead of a quick tunnel

• Confirm GET /mcp returns text/event-stream

delegate_task fails

• Check codex --help

• Check claude --help

• Set NOTION_LOCAL_OPS_CODEX_COMMAND or NOTION_LOCAL_OPS_CLAUDE_COMMAND if needed