Notion Terminal MCP

Un servidor remoto Model Context Protocol (MCP) autenticado y listo para producción que proporciona Ejecución de Terminal y Herramientas de Sistema de Archivos a Agentes Personalizados de Notion, Claude, Cursor y agentes de IA autónomos a través de Streamable HTTP.

Incluye túnel público integrado sin configuración a través del SDK oficial de Ngrok para Node.js (@ngrok/ngrok).

Características

• ⚡ Transporte HTTP Streamable: Implementación moderna de servidor MCP ejecutándose en Express.

• 🌐 Túnel Ngrok Integrado: Exponga su servidor MCP local a Notion con un solo comando (npm run start o npm run dev) usando @ngrok/ngrok.

• 💻 Ejecución de Terminal: Ejecute comandos de PowerShell o cmd con tiempos de espera configurables, directorios de trabajo y terminación recursiva del árbol de procesos.

• 📁 Operaciones de Sistema de Archivos: Conjunto completo de herramientas para leer, escribir, mover, listar, inspeccionar y eliminar archivos y directorios.

• 🔒 Seguridad y Sandboxing:

  • Modo Sandbox (FULL_ACCESS=false): Contención estricta de rutas dentro de un FILES_ROOT configurado con defensa contra traversal de rutas.

  • Modo Host Completo (FULL_ACCESS=true): Acceso sin restricciones cuando necesite automatización completa del host.

  • Autenticación Segura en Tiempo: Comparación en tiempo constante (crypto.timingSafeEqual) para tokens Bearer y claves API.

  • Validación de Cabecera Host: Previene el rebinding de DNS y la suplantación no autorizada de cabeceras Host.

• 🤖 Diseño Primero para Agentes: Especificaciones detalladas y esquemas JSON optimizados para modelos de IA (AGENT_SPEC.md).

Inicio Rápido

1. Instalación

Clone el repositorio e instale las dependencias:

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

2. Configuración del Entorno

Copie .env.example a .env o ejecute el script de configuración:

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

O manualmente:

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

Edite su archivo .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. Compilar y Ejecutar

# Build TypeScript
npm run build

# Start production server
npm run start

Para desarrollo con recarga en caliente:

npm run dev

Cuando se inicie con NGROK_ENABLED=true, el servidor mostrará los detalles de conexión listos para pegar en 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>
============================================================

Conexión a Agentes Personalizados de Notion

1. En Notion, abra Configuración y miembros → Conexiones (o abra su configuración de Agente de Notion).

2. Agregue una nueva Conexión MCP Personalizada.

3. Establezca la URL del servidor a:

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

4. Establezca la Autenticación:

   • Nombre de cabecera: Authorization

   • Valor de cabecera: Bearer <YOUR_MCP_API_KEY>

5. Pruebe la conexión. Notion descubrirá automáticamente las 7 herramientas (terminal_execute, file_read, file_write, file_list, file_stat, file_mkdir, file_move, file_delete).

Herramientas MCP Disponibles

Consulte AGENT_SPEC.md para ver los esquemas JSON completos, parámetros y tipos de retorno.

Referencia de Configuración (.env)

Estructura del Proyecto

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

Scripts de NPM

• npm run build — Compilar TypeScript a dist/.

• npm run start — Ejecutar el servidor de producción desde dist/index.js.

• npm run dev — Ejecutar el servidor de desarrollo con tsx watch.

• npm run check — Verificar tipos de TypeScript sin emitir archivos.

• npm run token — Generar un token aleatorio criptográficamente seguro para MCP_API_KEY.

Política de Seguridad

Revise SECURITY.md para conocer las consideraciones de seguridad y las pautas de notificación de vulnerabilidades.