notion-local-ops-mcp

Notion AIをローカルファイル、シェル、およびフォールバック用のローカルエージェントと連携させます。

📖 プロジェクト紹介 (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: ローカルシェルコマンドの実行

• 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を設定してください