notion-local-ops-mcp

Nutzen Sie Notion AI mit Ihren lokalen Dateien, der Shell und lokalen Fallback-Agenten.

📖 Projekteinführung (Notion-Seite)

Was es bietet

• list_files

• search_files

• read_file

• replace_in_file

• write_file

• run_command

• delegate_task

• get_task

• cancel_task

delegate_task unterstützt lokale codex- und claude-CLIs.

Anforderungen

• Python 3.11+

• cloudflared

• Notion Custom Agent mit Unterstützung für benutzerdefinierte MCPs

• Optional: codex CLI

• Optional: claude CLI

Installation

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 .

Konfiguration

Kopieren Sie .env.example und setzen Sie mindestens:

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

Lokaler Endpunkt:

http://127.0.0.1:8766/mcp

Bereitstellung mit cloudflared

Quick Tunnel

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

Verwenden Sie die generierte HTTPS-URL mit /mcp.

Benannter Tunnel

Bearbeiten Sie cloudflared-example.yml und führen Sie dann Folgendes aus:

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

Zu Notion hinzufügen

Verwenden Sie:

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

• Authentifizierungstyp: Bearer

• Token: Ihr NOTION_LOCAL_OPS_AUTH_TOKEN

Empfohlene Agenten-Anweisung:

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.

Umgebungsvariablen

Hinweise zu den Tools

• list_files: Dateien und Verzeichnisse auflisten

• search_files: Text in Dateien suchen

• read_file: Textdateien mit Offset und Limit lesen

• replace_in_file: Ein exaktes Textfragment ersetzen

• write_file: Vollständigen Dateiinhalt schreiben

• run_command: Lokale Shell-Befehle ausführen

• delegate_task: Eine Aufgabe an lokales codex oder claude senden

• get_task: Aufgabenstatus und Ausgabe-Ende lesen

• cancel_task: Eine delegierte Aufgabe stoppen

Überprüfung

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

Fehlerbehebung

Notion meldet, dass keine Verbindung hergestellt werden kann

• Überprüfen Sie, ob die URL auf /mcp endet

• Überprüfen Sie, ob der Authentifizierungstyp Bearer ist

• Überprüfen Sie, ob das Token mit NOTION_LOCAL_OPS_AUTH_TOKEN übereinstimmt

• Überprüfen Sie, ob cloudflared noch läuft

SSE-Pfad funktioniert lokal, aber nicht über den Tunnel

• Versuchen Sie es mit einem benannten Tunnel anstelle eines Quick Tunnels

• Bestätigen Sie, dass GET /mcp den Typ text/event-stream zurückgibt

delegate_task schlägt fehl

• Überprüfen Sie codex --help

• Überprüfen Sie claude --help

• Setzen Sie bei Bedarf NOTION_LOCAL_OPS_CODEX_COMMAND oder NOTION_LOCAL_OPS_CLAUDE_COMMAND