認証済みで本番環境に対応したリモートのModel Context Protocol (MCP)サーバーであり、Notion Custom Agents、Claude、Cursor、および自律型AIエージェントに対して、Streamable HTTPを介してターミナル実行とファイルシステムツールを提供します。
公式のNgrok Node.js SDK（@ngrok/ngrok）による、設定不要のパブリックトンネリングを内蔵しています。
⚡ Streamable HTTP トランスポート: Express上で動作する最新のMCPサーバー実装です。
🌐 内蔵Ngrokトンネル: @ngrok/ngrokを使用して、単一のコマンド（npm run start または npm run dev）でローカルMCPサーバーをNotionに公開します。
💻 ターミナル実行: PowerShellまたはcmdコマンドを、設定可能なタイムアウト、作業ディレクトリ、再帰的なプロセスツリー終了とともに実行します。
📁 ファイルシステム操作: ファイルとディレクトリの読み取り、書き込み、移動、一覧表示、状態取得、削除のための完全なツールセットです。
🔒 セキュリティとサンドボックス:
サンドボックスモード（FULL_ACCESS=false）: 設定されたFILES_ROOT内での厳格なパス封じ込めと、パストラバーサル防御を提供します。
フルホストモード（FULL_ACCESS=true）: 完全なホスト自動化が必要な場合の無制限アクセス。
タイミングセーフ認証: BearerトークンとAPIキーに対する定数時間比較（crypto.timingSafeEqual）。
ホストヘッダー検証: DNSリバインディングと不正なホストヘッダースプーフィングを防止します。
🤖 エージェントファースト設計: AIモデル向けに最適化された詳細な仕様とJSONスキーマ（AGENT_SPEC.md）。
Related MCP server: localmcpcoder
リポジトリをクローンして依存関係をインストールします:
git clone https://github.com/Speedstu/notion-terminal-mcp.git
cd notion-terminal-mcp
npm install.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# Build TypeScript
npm run build
# Start production server
npm run startホットリロードでの開発用:
npm run devNGROK_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で、設定とメンバー → 接続 を開きます（またはNotion Agent設定を開きます）。
新しいカスタムMCP接続を追加します。
サーバーURLを次に設定します:
https://your-domain.ngrok-free.app/mcp認証を設定します:
ヘッダー名: Authorization
ヘッダー値: Bearer <YOUR_MCP_API_KEY>
接続をテストします。Notionは自動的に7つのツール（terminal_execute、file_read、file_write、file_list、file_stat、file_mkdir、file_move、file_delete）を検出します。
完全なJSONスキーマ、パラメータ、戻り値の型については、AGENT_SPEC.mdを参照してください。
Tool | Description |
| PowerShellまたはcmdコマンドを、UTF-8エンコーディングとタイムアウトオプション付きで実行します。 |
| ファイル名のグロブ（ |
| ファイル内の正確なコードまたはテキストのブロックを、完全に書き換えることなく安全に置換します。 |
| ファイル内容を読み取ります（UTF-8またはBase64）。大きなファイルにはオフセットページネーションを使用します。 |
| ファイルにコンテンツを作成、上書き、または追加します（不足しているディレクトリも作成します）。 |
| ディレクトリ内容を再帰的またはフラットに、ファイルサイズ付きで一覧表示します。 |
| ファイル/ディレクトリのメタデータ（サイズ、作成/変更タイムスタンプ、モード）を検査します。 |
| ディレクトリを再帰的に作成します。 |
| ファイルとディレクトリを移動または名前変更します。 |
| ファイルまたはディレクトリを安全に削除します（ディレクトリには |
.env)Variable | Default | Description |
| required | 認証用の秘密鍵（最小32文字）。 |
|
| HTTPサーバーのポート。 |
|
| バインドするホストアドレス。 |
|
| 起動時に自動ngrokトンネル作成を有効/無効にします。 |
|
| Ngrok authtoken（ngrok CLIでグローバルに設定されている場合は任意）。 |
|
| 静的/カスタムngrokドメイン（例: |
|
| 許可された |
|
|
|
|
|
|
|
| ターミナルコマンドのデフォルトタイムアウト（2分）。 |
|
| stdout/stderrキャプチャの最大サイズ（1 MB）。 |
|
| リクエストごとのファイル読み書きの最大サイズ（10 MB）。 |
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 scriptnpm 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を確認してください。
This server cannot be deployed
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Remote Desktop Commander: use files, terminal and processes on your own computers from any AI app.
