notion-local-ops-mcp

Utiliza Notion AI con tus archivos locales, shell y agentes locales de respaldo.

📖 Introducción al proyecto (Página de Notion)

Qué proporciona

• list_files

• search_files

• read_file

• replace_in_file

• write_file

• run_command

• delegate_task

• get_task

• cancel_task

delegate_task es compatible con las CLI locales codex y claude.

Requisitos

• Python 3.11+

• cloudflared

• Agente personalizado de Notion con soporte MCP personalizado

• Opcional: CLI codex

• Opcional: CLI claude

Instalación

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 .

Configuración

Copia .env.example y establece al menos:

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

Opcional:

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"

Inicio

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

Endpoint local:

http://127.0.0.1:8766/mcp

Exponer con cloudflared

Túnel rápido

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

Utiliza la URL HTTPS generada con /mcp.

Túnel con nombre

Edita cloudflared-example.yml y luego ejecuta:

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

Añadir a Notion

Utiliza:

• URL: https://<tu-dominio-o-túnel>/mcp

• Tipo de autenticación: Bearer

• Token: tu NOTION_LOCAL_OPS_AUTH_TOKEN

Instrucción recomendada para el agente:

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.

Variables de entorno

Notas sobre las herramientas

• list_files: listar archivos y directorios

• search_files: buscar texto en archivos

• read_file: leer archivos de texto con desplazamiento y límite

• replace_in_file: reemplazar un fragmento de texto exacto

• write_file: escribir el contenido completo del archivo

• run_command: ejecutar comandos de shell locales

• delegate_task: enviar una tarea a codex o claude local

• get_task: leer el estado de la tarea y el final de la salida

• cancel_task: detener una tarea delegada

Verificación

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

Solución de problemas

Notion dice que no puede conectar

• Comprueba que la URL termine en /mcp

• Comprueba que el tipo de autenticación sea Bearer

• Comprueba que el token coincida con NOTION_LOCAL_OPS_AUTH_TOKEN

• Comprueba que cloudflared siga ejecutándose

La ruta SSE funciona localmente pero no a través del túnel

• Vuelve a intentarlo con un túnel con nombre en lugar de un túnel rápido

• Confirma que GET /mcp devuelve text/event-stream

delegate_task falla

• Comprueba codex --help

• Comprueba claude --help

• Establece NOTION_LOCAL_OPS_CODEX_COMMAND o NOTION_LOCAL_OPS_CLAUDE_COMMAND si es necesario