Notion Terminal MCP

Ein authentifizierter, produktionsreifer Remote-Model Context Protocol (MCP)-Server, der Terminal-Ausführung und Dateisystem-Tools für Notion Custom Agents, Claude, Cursor und autonome KI-Agenten über Streamable HTTP bereitstellt.

Enthält integriertes Zero-Config-Public-Tunneling über das offizielle Ngrok Node.js SDK (@ngrok/ngrok).

Funktionen

• ⚡ Streamable HTTP Transport: Moderne MCP-Server-Implementierung, die auf Express läuft.

• 🌐 Integrierter Ngrok-Tunnel: Stellen Sie Ihren lokalen MCP-Server mit einem einzigen Befehl (npm run start oder npm run dev) über @ngrok/ngrok für Notion bereit.

• 💻 Terminal-Ausführung: Führen Sie PowerShell- oder cmd-Befehle mit konfigurierbaren Timeouts, Arbeitsverzeichnissen und rekursiver Prozessbaum-Beendigung aus.

• 📁 Dateisystem-Operationen: Vollständiger Satz von Werkzeugen zum Lesen, Schreiben, Verschieben, Auflisten, Abfragen von Dateiinformationen und Löschen von Dateien und Verzeichnissen.

• 🔒 Sicherheit & Sandboxing:

  • Sandbox-Modus (FULL_ACCESS=false): Strikte Pfadbegrenzung innerhalb eines konfigurierten FILES_ROOT mit Schutz vor Pfad-Traversal.

  • Vollzugriffsmodus (FULL_ACCESS=true): Uneingeschränkter Zugriff, wenn Sie vollständige Host-Automatisierung benötigen.

  • Timing-sichere Authentifizierung: Vergleich in konstanter Zeit (crypto.timingSafeEqual) für Bearer-Tokens und API-Schlüssel.

  • Host-Header-Validierung: Verhindert DNS-Rebinding und unbefugtes Spoofing von Host-Headern.

• 🤖 Agent-First-Design: Detaillierte Spezifikationen und JSON-Schemas, optimiert für KI-Modelle (AGENT_SPEC.md).

Schnellstart

1. Installation

Klonen Sie das Repository und installieren Sie die Abhängigkeiten:

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

2. Umgebungseinrichtung

Kopieren Sie .env.example in .env oder führen Sie das Setup-Skript aus:

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

Oder manuell:

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

Bearbeiten Sie Ihre .env-Datei:

# 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. Erstellen & Ausführen

# Build TypeScript
npm run build

# Start production server
npm run start

Für die Entwicklung mit Hot Reload:

npm run dev

Wenn der Server mit NGROK_ENABLED=true gestartet wird, gibt er Verbindungsdetails aus, die Sie direkt in Notion einfügen können:

============================================================
             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>
============================================================

Verbinden mit Notion Custom Agents

1. Öffnen Sie in Notion Einstellungen & Mitglieder → Verbindungen (oder öffnen Sie Ihre Notion-Agent-Konfiguration).

2. Fügen Sie eine neue Benutzerdefinierte MCP-Verbindung hinzu.

3. Setzen Sie die Server-URL auf:

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

4. Legen Sie die Authentifizierung fest:

   • Header-Name: Authorization

   • Header-Wert: Bearer <YOUR_MCP_API_KEY>

5. Testen Sie die Verbindung. Notion erkennt automatisch alle 7 Tools (terminal_execute, file_read, file_write, file_list, file_stat, file_mkdir, file_move, file_delete).

Verfügbare MCP-Tools

Siehe AGENT_SPEC.md für vollständige JSON-Schemas, Parameter und Rückgabetypen.

Konfigurationsreferenz (.env)

Projektstruktur

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-Skripte

• npm run build — Kompiliert TypeScript nach dist/.

• npm run start — Führt den Produktionsserver aus dist/index.js aus.

• npm run dev — Führt den Entwicklungsserver mit tsx watch aus.

• npm run check — Typüberprüfung von TypeScript ohne Dateiausgabe.

• npm run token — Generiert ein kryptographisch sicheres Zufalls-Token für MCP_API_KEY.

Sicherheitsrichtlinie

Bitte lesen Sie SECURITY.md für Sicherheitsüberlegungen und Richtlinien zur Meldung von Schwachstellen.