Notion Local MCP Easy 1.3.2

One-click Windows MCP-сервер для личного использования с Notion Agent. Агент получает инструменты для чтения, поиска и изменения файлов в выбранной рабочей папке. При необходимости можно отдельно включить доверенный developer-режим с Python, Git, Node и тестами.

Проект предназначен для собственного компьютера и доверенного Notion Agent. Это не многопользовательский публичный сервис.

Запуск за несколько минут

1. Распакуйте архив в любую папку.
2. Дважды кликните START.bat.
3. При первом запуске выберите рабочую папку.
4. Оставьте trusted developer mode выключенным, если нужны только файловые инструменты. Для написания и запуска кода его можно включить ответом y.
5. Скопируйте показанные URL и Bearer token в Custom MCP вашего Notion Agent.
6. Не закрывайте окно запуска во время работы.

При последующих запусках повторная настройка не требуется. Конфигурация хранится в %LOCALAPPDATA%\NotionMcpEasy и не входит в архив проекта.

Управление

• START.bat — создать локальное .venv, установить зависимости и запустить сервер с туннелем.
• STOP.bat — остановить только процессы этого MCP после проверки их идентичности.
• SETUP.bat — выбрать другую рабочую папку, режим и сгенерировать новый токен.
• SHOW_CONNECTION.bat — показать текущие URL, токен, workspace и режим.

Режимы

File-only mode — по умолчанию

Файловые инструменты разрешены только внутри выбранного workspace. Пути нормализуются, а выход через .., абсолютные пути и ссылки наружу отклоняется.

Trusted developer mode — опционально

Добавляет запуск разрешённых программ без cmd.exe и PowerShell:

python, py, pip, git, node, npm, npx, pytest, ruff, make, uv

Это не песочница. Python, Node, Git hooks, npm scripts и другие инструменты могут обращаться ко всей системе и сети с правами текущего пользователя Windows. Включайте режим только для личного доверенного агента.

Архитектура

Notion Agent
    -> HTTPS + Bearer token
Serveo SSH reverse tunnel
    -> 127.0.0.1:8765
FastMCP server
    -> выбранный workspace

Сервер слушает только localhost. Все HTTP-маршруты, включая /health, требуют токен. FastMCP Host-проверка отключена намеренно: Serveo выдаёт случайное публичное имя, которое иначе приводило бы к HTTP 421.

Serveo — сторонний туннель. В быстром анонимном режиме URL меняется после перезапуска. Если в Serveo зарезервировать hostname и добавить SSH-ключ, мастер включает stable mode: адрес вида https://my-name.serveousercontent.com/mcp сохраняется после перезапусков и добавляется в Notion один раз.

Инструменты

• workspace_info — workspace и активный режим;
• list_dir, file_info, read_file;
• write_file, append_file, edit_file;
• create_dir, безопасное нерекурсивное delete_file;
• copy_file, move_file — только отдельные файлы;
• glob_files, ограниченный текстовый grep_files;
• run_command — только в trusted developer mode.

Regex-поиск отключён, чтобы исключить зависание на патологических выражениях. Обычный регистронезависимый поиск остаётся доступен.

Ограничения

• текстовый файл для чтения и итогового append/edit: до 5 МБ;
• один write/append: до 2 МБ;
• одна выдача команды: до 200 КБ суммарно для stdout+stderr;
• при превышении вывода или timeout дерево процесса останавливается;
• рекурсивное удаление и перемещение каталогов через MCP отсутствуют;
• node_modules, .venv, .git и кэши пропускаются при рекурсивном просмотре.

Требования

• Windows 10/11;
• Python 3.11+ с опцией Add Python to PATH;
• встроенный OpenSSH Client (ssh.exe);
• интернет при первой установке и для Serveo.

Проверка

.venv\Scripts\python -m unittest discover -s tests -v
.venv\Scripts\ruff check .

Тесты покрывают path traversal, allowlist, занятый порт, PID-проверку, правильный и неправильный токены, Serveo Host без HTTP 421, лимит вывода и timeout процесса.

Что улучшено относительно оригинала

• автоматический setup без ручного редактирования BAT-файлов;
• токен и runtime вне проекта;
• localhost-only bind и обязательная Bearer-авторизация;
• правильная проверка границ workspace;
• файловый режим безопаснее и включён по умолчанию;
• команды вынесены в явно доверенный режим;
• нет shell, фоновых команд, HTTP downloader и чтения env через MCP;
• потоковый лимит вывода вместо накопления всего stdout в памяти;
• проверка занятого порта до создания туннеля;
• проверка идентичности PID перед остановкой;
• фиксированные зависимости, тесты, changelog и security model.

Подробная модель безопасности: SECURITY.md. История версий: CHANGELOG.md.

Сборка архива для отправки

Запустите BUILD_RELEASE.bat. Архив notion-mcp-easy-<версия>.zip появится рядом с папкой проекта. Сборщик автоматически исключает .venv, кэши, логи, ZIP-файлы и файлы конфигурации/токенов.

Полный гайд Serveo

Подробная инструкция по временному и постоянному URL, созданию аккаунта, SSH-ключа, резервированию hostname, настройке Notion и устранению ошибок находится в SERVEO_SETUP.md.