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 поддерживает локальные CLI codex и claude.

Требования

• Python 3.11+

• cloudflared

• Пользовательский агент Notion с поддержкой пользовательского MCP

• Опционально: 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