Notion Terminal MCP

An authenticated, production-ready remote Model Context Protocol (MCP) server providing Terminal Execution and Filesystem Tools to Notion Custom Agents, Claude, Cursor, and autonomous AI agents over Streamable HTTP.

Includes built-in zero-config public tunneling via the official Ngrok Node.js SDK (@ngrok/ngrok).

Features

• ⚡ Streamable HTTP Transport: Modern MCP server implementation running on Express.

• 🌐 Built-in Ngrok Tunnel: Expose your local MCP server to Notion with a single command (npm run start or npm run dev) using @ngrok/ngrok.

• 💻 Terminal Execution: Execute PowerShell or cmd commands with configurable timeouts, working directories, and recursive process tree termination.

• 📁 Filesystem Operations: Full set of tools for reading, writing, moving, listing, statting, and deleting files and directories.

• 🔒 Security & Sandboxing:

  • Sandboxed Mode (FULL_ACCESS=false): Strict path containment inside a configured FILES_ROOT with path traversal defense.

  • Full Host Mode (FULL_ACCESS=true): Unrestricted access when you need full host automation.

  • Timing-Safe Auth: Constant-time comparison (crypto.timingSafeEqual) for Bearer tokens and API keys.

  • Host Header Validation: Prevents DNS rebinding and unauthorized host header spoofing.

• 🤖 Agent-First Design: Detailed specifications and JSON schemas optimized for AI models (AGENT_SPEC.md).

Quick Start

1. Installation

Clone the repository and install dependencies:

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

2. Environment Setup

Copy .env.example to .env or run the setup script:

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

Or manually:

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

Edit your .env file:

# 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 & Run

# Build TypeScript
npm run build

# Start production server
npm run start

For development with hot reload:

npm run dev

When started with NGROK_ENABLED=true, the server will output connection details ready to paste into 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>
============================================================

Connecting to Notion Custom Agents

1. In Notion, open Settings & members → Connections (or open your Notion Agent configuration).

2. Add a new Custom MCP Connection.

3. Set Server URL to:

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

4. Set Authentication:

   • Header Name: Authorization

   • Header Value: Bearer <YOUR_MCP_API_KEY>

5. Test the connection. Notion will automatically discover all 7 tools (terminal_execute, file_read, file_write, file_list, file_stat, file_mkdir, file_move, file_delete).

Available MCP Tools

See AGENT_SPEC.md for full JSON schemas, parameters, and return types.

Configuration Reference (.env)

Project Structure

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 Scripts

• npm run build — Compile TypeScript to dist/.

• npm run start — Run production server from dist/index.js.

• npm run dev — Run development server with tsx watch.

• npm run check — Type-check TypeScript without emitting files.

• npm run token — Generate a cryptographically secure random token for MCP_API_KEY.

Security Policy

Please review SECURITY.md for security considerations and vulnerability reporting guidelines.