Notion Terminal MCP

Аутентифицированный, готовый к продакшену удалённый Model Context Protocol (MCP) сервер, предоставляющий выполнение команд терминала и инструменты файловой системы для Notion Custom Agents, Claude, Cursor и автономных AI-агентов через Streamable HTTP.

Включает встроенный публичный туннель с нулевой конфигурацией через официальный Ngrok Node.js SDK (@ngrok/ngrok).

Возможности

• ⚡ Streamable HTTP Transport: Современная реализация MCP-сервера на Express.

• 🌐 Встроенный Ngrok-туннель: Откройте доступ к вашему локальному MCP-серверу для Notion одной командой (npm run start или npm run dev) с помощью @ngrok/ngrok.

• 💻 Выполнение команд терминала: Выполняйте команды PowerShell или cmd с настраиваемыми таймаутами, рабочими каталогами и рекурсивным завершением дерева процессов.

• 📁 Операции с файловой системой: Полный набор инструментов для чтения, записи, перемещения, просмотра списка, получения информации и удаления файлов и каталогов.

• 🔒 Безопасность и песочница:

  • Режим песочницы (FULL_ACCESS=false): Строгое ограничение путей внутри настроенного FILES_ROOT с защитой от обхода пути.

  • Полный доступ к хосту (FULL_ACCESS=true): Неограниченный доступ, когда вам нужна полная автоматизация хоста.

  • Безопасная аутентификация: Сравнение за постоянное время (crypto.timingSafeEqual) для Bearer-токенов и API-ключей.

  • Проверка заголовка Host: Предотвращает DNS-ребдинг и несанкционированную подмену заголовка Host.

• 🤖 Дизайн, ориентированный на агентов: Подробные спецификации и JSON-схемы, оптимизированные для AI-моделей (AGENT_SPEC.md).

Быстрый старт

1. Установка

Клонируйте репозиторий и установите зависимости:

git clone https://github.com/Speedstu/notion-terminal-mcp.git
cd notion-terminal-mcp
npm install

2. Настройка окружения

Скопируйте .env.example в .env или запустите скрипт настройки:

# Automated setup (generates a secure 32+ character API key)
.\setup.ps1

Или вручную:

Copy-Item .env.example .env
# Generate a secure token:
npm run token

Отредактируйте ваш файл .env:

# Required: Secure API Key for Notion
MCP_API_KEY=your_generated_32_char_api_key

PORT=3000
HOST=127.0.0.1

# Ngrok Public Tunnel (Optional but recommended for Notion)
NGROK_ENABLED=true
NGROK_AUTHTOKEN=your_ngrok_authtoken_here
NGROK_DOMAIN=your-static-name.ngrok-free.app

# Security & Sandboxing
FULL_ACCESS=false
FILES_ROOT=./workspace
ALLOWED_HOSTS=localhost:3000;127.0.0.1:3000;*.ngrok-free.app;*.ngrok.app;*.ngrok-free.dev

3. Сборка и запуск

# Build TypeScript
npm run build

# Start production server
npm run start

Для разработки с горячей перезагрузкой:

npm run dev

При запуске с NGROK_ENABLED=true сервер выведет данные для подключения, готовые для вставки в Notion:

============================================================
             NOTION MCP AGENT CONNECTION READY             
============================================================
URL to paste into Notion:  https://your-domain.ngrok-free.app/mcp

Authentication Header:
  Header Name:   Authorization
  Header Value:  Bearer <your_token>
============================================================

Подключение к Notion Custom Agents

1. В Notion откройте Settings & members → Connections (или откройте конфигурацию вашего Notion Agent).

2. Добавьте новое Custom MCP Connection.

3. Установите Server URL на:

   https://your-domain.ngrok-free.app/mcp

4. Установите Authentication:

   • Header Name: Authorization

   • Header Value: Bearer <YOUR_MCP_API_KEY>

5. Проверьте подключение. Notion автоматически обнаружит все 7 инструментов (terminal_execute, file_read, file_write, file_list, file_stat, file_mkdir, file_move, file_delete).

Доступные MCP-инструменты

Полные JSON-схемы, параметры и типы возвращаемых значений см. в AGENT_SPEC.md.

Справочник по конфигурации (.env)

Структура проекта

notion-terminal-mcp/
├── src/
│   ├── config.ts              # Type-safe environment and validation
│   ├── index.ts               # Server entry point & lifecycle
│   ├── server.ts              # Express setup & MCP Streamable HTTP endpoint
│   ├── middleware/
│   │   ├── auth.ts            # Timing-safe token authentication
│   │   └── host.ts            # Host header validation
│   ├── tools/
│   │   ├── command.ts         # Process tree management & execution
│   │   ├── filesystem.ts      # Sandboxed filesystem CRUD operations
│   │   ├── index.ts           # MCP tool registrations
│   │   └── types.ts           # MCP result helpers & interfaces
│   └── tunnel/
│       └── ngrok.ts           # Ngrok SDK manager & Notion connection banner
├── AGENT_SPEC.md              # Technical specification for AI Agents
├── package.json
├── tsconfig.json
└── setup.ps1                  # PowerShell initial setup script

NPM-скрипты

• npm run build — Компиляция TypeScript в dist/.

• npm run start — Запуск продакшен-сервера из dist/index.js.

• npm run dev — Запуск сервера разработки с tsx watch.

• npm run check — Проверка типов TypeScript без создания файлов.

• npm run token — Генерация криптографически безопасного случайного токена для MCP_API_KEY.

Политика безопасности

Пожалуйста, ознакомьтесь с SECURITY.md для получения информации о вопросах безопасности и рекомендациях по сообщению об уязвимостях.