interactive-terminal

mcp-interactive-terminal

AI エージェント（Claude Code、Cursor、Windsurf など）に、実際に操作できるターミナルセッションを提供する MCP サーバーです。REPL、SSH、データベースクライアント、あらゆる対話型 CLI を、整ったテキスト出力、スマートな完了検知、7 層のセキュリティとともに実行できます。

開発の背景

AI コーディングエージェントは対話型コマンドを扱えません。PTY も stdin のストリーミングもありません。rails console、python、psql、ssh や REPL を実行できません。この MCP サーバーがその問題を解決します。

AI Agent (Claude Code, Cursor, etc.)
    ↕  MCP (JSON-RPC over stdio)
mcp-interactive-terminal
    ↕  node-pty + xterm-headless
Interactive Process (rails console, python, psql, ssh, bash...)
    ↕
Clean text output (exactly what a human would see)

インストール

Claude Code

claude mcp add terminal -- npx -y mcp-interactive-terminal

これで完了です。サーバーが利用可能になりました。Claude に「python REPL を開いて 2**100 を計算して」と頼んでみてください。

Cursor

Settings > MCP Servers に移動して、Add Server をクリックし、次の内容を入力します。

{
  "mcpServers": {
    "terminal": {
      "command": "npx",
      "args": ["-y", "mcp-interactive-terminal"]
    }
  }
}

Windsurf

MCP 設定に追加します。

{
  "mcpServers": {
    "terminal": {
      "command": "npx",
      "args": ["-y", "mcp-interactive-terminal"]
    }
  }
}

VS Code（GitHub Copilot）

.vscode/mcp.json に追加します。

{
  "servers": {
    "terminal": {
      "command": "npx",
      "args": ["-y", "mcp-interactive-terminal"]
    }
  }
}

任意の MCP クライアント

サーバーは Model Context Protocol を使用して stdio 経由で通信します。MCP 対応クライアントであれば、同じ npx -y mcp-interactive-terminal コマンドで利用できます。

実際の使用例

Rails コンソール

You: "Open rails console for staging and check the user count"

Agent creates session → bash
Agent sends: cd /path/to/app && rails console -e staging
Agent sends: User.count
Agent returns: 1,847,293

Python REPL

You: "Open python and test my sorting algorithm"

Agent creates session → python3
Agent sends: def quicksort(arr): ...
Agent sends: quicksort([3, 1, 4, 1, 5, 9])
Agent returns: [1, 1, 3, 4, 5, 9]

データベースクライアント

You: "Connect to postgres and show me the largest tables"

Agent creates session → psql -U myuser mydb
Agent sends: SELECT tablename, pg_size_pretty(pg_total_relation_size(tablename::text)) ...
Agent returns: formatted table of results

SSH

You: "SSH into the staging server and check disk usage"

Agent creates session → ssh [email protected]
Agent sends: df -h
Agent returns: disk usage table

Docker

You: "Open a shell in my running container and check the logs"

Agent creates session → docker exec -it my-container bash
Agent sends: tail -100 /var/log/app.log
Agent returns: last 100 log lines

Node.js REPL

You: "Open node and test the date parsing logic"

Agent creates session → node
Agent sends: new Date('2024-02-29').toISOString()
Agent returns: 2024-02-29T00:00:00.000Z

ツール

このサーバーは 7 つの MCP ツールを公開します。

create_session — 対話型プロセスを起動

{ "command": "python3", "name": "my-python", "cwd": "/project" }
→ { "session_id": "a1b2c3d4", "name": "my-python", "pid": 12345 }

パラメーター	必須	デフォルト	説明
command	はい	—	実行するコマンド（bash、python3、psql、ssh など）
args	いいえ	[]	コマンドの引数
name	いいえ	auto	人が読みやすいセッション名
cwd	いいえ	server cwd	作業ディレクトリ
env	いいえ	{}	追加の環境変数
cols	いいえ	120	ターミナルの列数
rows	いいえ	40	ターミナルの行数

send_command — 入力を送信して出力を取得

{ "session_id": "a1b2c3d4", "input": "1 + 1" }
→ { "output": "2", "is_complete": true, "is_alive": true }

パラメーター	必須	デフォルト	説明
session_id	はい	—	対象のセッション
input	はい	—	送信するコマンド／入力（改行は自動的に追加されます）
timeout_ms	いいえ	5000	出力を待つ最大時間
max_output_chars	いいえ	20000	これを超える出力を切り詰めます

危険なコマンド（rm -rf、DROP TABLE、curl|bash など）はブロックされます。エージェントは先に confirm_dangerous_command を使用する必要があります。

read_output — ターミナル画面を読み取る（読み取り専用）

{ "session_id": "a1b2c3d4" }
→ { "output": ">>> ", "is_alive": true }

読み取りのみで入力は送信しないため、自動承認しても安全です。

list_sessions — アクティブなセッションを一覧表示（読み取り専用）

→ [{ "session_id": "a1b2c3d4", "name": "my-python", "command": "python3", "pid": 12345, "is_alive": true }]

自動承認しても安全です。

close_session — セッションを終了

{ "session_id": "a1b2c3d4" }
→ { "success": true }

send_control — 制御文字を送信

{ "session_id": "a1b2c3d4", "control": "ctrl+c" }
→ { "output": "^C\n>>>" }

対応する入力：ctrl+c、ctrl+d、ctrl+z、ctrl+l、ctrl+r、tab、escape、up、down、left、right、enter、backspace、delete、home、end など。

confirm_dangerous_command — 2 段階の安全確認

{ "session_id": "a1b2c3d4", "input": "rm -rf /tmp/old", "justification": "Cleaning up stale temp files from failed build" }
→ { "output": "...", "is_complete": true, "is_alive": true }

send_command が危険なパターンを検知した場合に必要です。エージェントは、そのコマンドが必要な理由を説明しなければなりません。これは別個のツールです。send_command が自動承認されていても、このツールには個別の許可が必要です。

仕組み

2 つのターミナルモード

PTY モード（デフォルト）— node-pty と @xterm/headless（VS Code と同じターミナルエミュレーター）を使用します。

• クリーンな出力 — AI には、人間が画面で見るのとまったく同じ内容が表示されます
• カーソル位置、プログレスバー、\r による上書きをすべて正しく描画します
• フルキーボード対応：矢印キー、タブ補完、ctrl+c/d/z、home/end
• ターミナルのサイズ変更、TUI アプリ（vim、htop、top）、256 色、1000 行のスクロールバック

パイプモード（自動フォールバック）— node-pty を読み込めない場合（サンドボックス環境など）に有効になります。

• child_process.spawn と自動挿入されるフラグ（python -u -i、bash -i など）を使い、インタラクティブセッションも引き続き動作します
• ANSI コードは削除され、制御キーも引き続き動作します
• ターミナルエミュレーションはありませんが、基本的な機能をカバーします

モードは自動的に選択されます。最初に PTY を試し、失敗した場合はパイプモードに切り替わります。

AI に表示される内容：PTY とパイプの比較

シナリオ	PTY モード	パイプモード
printf "\rProgress: 3/3"	Progress: 3/3	Progress: 1/3Progress: 2/3Progress: 3/3
ANSI カラー	きれいに削除	正規表現で削除
vim、htop、top	読みやすい画面	文字化け
矢印キー、タブ補完	動作します	動作します
ターミナルのサイズ変更	動作します	何もしません

スマートな「コマンド完了」検出

固定時間をむやみに待つのではなく、サーバーは段階的な方法を使用します。

1. プロセスの終了 — プロセスが終了していれば、コマンドは完了です
2. プロンプトの検出 — 起動時にセッションのプロンプト（bash の $、python の >>>、psql の # など）を自動検出し、再び表示されるかを監視します
3. 出力の安定 — 300ms 間、新しい出力がなければ、ほぼ完了です
4. タイムアウト — timeout_ms 経過後には必ず返し、is_complete: false を返します

セキュリティ

多層防御による 7 つのセキュリティ対策：

レイヤー	動作	デフォルト
MCP ツールのアノテーション	各ツールに readOnlyHint／destructiveHint を設定	常に有効
確認フロー	危険なパターンには confirm_dangerous_command が必要	常に有効
入力パターンの検出	rm -rf、DROP TABLE、curl|bash などを検出	常に有効
コマンドのブロックリスト／許可リスト	特定のコマンドをブロック／許可	設定可能
OS レベルのサンドボックス	@anthropic-ai/sandbox-runtime によるカーネルレベルのプロセスサンドボックス化	オフ（オプトイン）
シークレットの秘匿	出力内の AWS キー、トークン、秘密鍵を秘匿	オフ（オプトイン）
リソース制限	セッションの最大数、出力上限、アイドルタイムアウト、監査ログ	常に有効

推奨される権限設定

読み取り専用のツールのみを自動承認してください。

{
  "permissions": {
    "allow": [
      "mcp__terminal__list_sessions",
      "mcp__terminal__read_output"
    ]
  }
}

この設定により、send_command、create_session、特に confirm_dangerous_command では、常に人間の承認が必要になります。

設定

すべての設定は環境変数で行います。MCP 設定で渡してください。

{
  "mcpServers": {
    "terminal": {
      "command": "npx",
      "args": ["-y", "mcp-interactive-terminal"],
      "env": {
        "MCP_TERMINAL_ALLOWED_COMMANDS": "bash,python3,node,psql",
        "MCP_TERMINAL_REDACT_SECRETS": "true",
        "MCP_TERMINAL_IDLE_TIMEOUT": "300000"
      }
    }
  }
}

変数	デフォルト	説明
MCP_TERMINAL_MAX_SESSIONS	10	同時セッションの最大数
MCP_TERMINAL_MAX_OUTPUT	20000	読み取りごとの出力文字数の上限
MCP_TERMINAL_DEFAULT_TIMEOUT	5000	デフォルトの待機タイムアウト（ms）
MCP_TERMINAL_BLOCKED_COMMANDS	—	カンマ区切りのブロックリスト
MCP_TERMINAL_ALLOWED_COMMANDS	—	カンマ区切りの許可リスト（設定すると、ここに含まれるコマンドのみ許可）
MCP_TERMINAL_ALLOWED_PATHS	—	セッションがアクセスできるパス（カンマ区切り）
MCP_TERMINAL_REDACT_SECRETS	false	出力内の AWS キー、トークン、秘密鍵を秘匿
MCP_TERMINAL_LOG_INPUTS	false	すべての入力を stderr に記録（デバッグ用）
MCP_TERMINAL_IDLE_TIMEOUT	1800000	アイドル状態のセッションを自動終了（ms、デフォルトは 30 分、0 = 無効）
MCP_TERMINAL_DANGER_DETECTION	true	危険なコマンドの確認フローを有効化
MCP_TERMINAL_AUDIT_LOG	—	JSON 監査ログファイルのパス
MCP_TERMINAL_SANDBOX	false	OS レベルのカーネルサンドボックス化を有効化
MCP_TERMINAL_SANDBOX_ALLOW_WRITE	/tmp	サンドボックスモードで書き込みを許可するパス
MCP_TERMINAL_SANDBOX_ALLOW_NETWORK	*	サンドボックスで許可するネットワークドメイン

トラブルシューティング

「ツールが表示されない」／サーバーがエラーを出さずに失敗する

起動に失敗した MCP サーバーは、クライアントにエラーが表示されないことがよくあります。次を確認してください。

# Test the server directly:
npx -y mcp-interactive-terminal

# You should see "[mcp-terminal] Starting MCP Interactive Terminal Server" on stderr.
# If you see an error, that's what's failing.

Node.js のバージョンが古すぎる

このサーバーには Node.js >= 18 が必要です。サポートされていない構文や API が見つからないというエラーが表示された場合は、次を確認してください。

node --version  # Must be >= 18

# If using nvm:
nvm install 18 && nvm use 18

# If using volta:
volta install node@18

nvm／volta／fnm のユーザー向け：npx はシェルとは異なる Node バージョンを使用する場合があります。絶対パスを使用してください。

{
  "mcpServers": {
    "terminal": {
      "command": "/Users/you/.nvm/versions/node/v22.0.0/bin/npx",
      "args": ["-y", "mcp-interactive-terminal"]
    }
  }
}

which npx を実行してパスを確認してください。

node-pty のコンパイルエラー

node-pty はビルドツールを必要とするネイティブモジュールです。コンパイルに失敗すると、サーバーは自動的にパイプモードに切り替わります。ターミナルエミュレーションは使えませんが、対話型セッションは引き続き動作します。

完全な PTY サポートが必要な場合は、次を実行してください。

# macOS:
xcode-select --install

# Ubuntu/Debian:
sudo apt-get install -y make python3 build-essential

# RHEL/Fedora:
sudo yum install -y make python3 gcc gcc-c++

セッションがすぐに終了する

一部のコマンドは、直接ではなくシェル内で実行する必要があります。

# Instead of:  create_session({ command: "rails console -e staging" })
# Do this:     create_session({ command: "bash" })
#              send_command({ input: "rails console -e staging" })

これは、create_session がシェルを介さず、exec のようにコマンドを直接実行するためです。先に bash を起動すると、完全なシェル環境が得られます。

出力が文字化けして見える

出力にエスケープコードが含まれている、または表示がおかしい場合は、パイプモード（node-pty の読み込みに失敗した状態）になっている可能性があります。サーバーログで "falling back to pipe mode" を確認してください。PTY モードを有効にするには、ビルドツールをインストールしてください（上記を参照）。

長時間実行されるコマンドのタイムアウトが短すぎる

コマンドごとにタイムアウトを延長してください。

{ "session_id": "...", "input": "bundle install", "timeout_ms": 60000 }

または、環境変数で全体のタイムアウトを設定してください。

{ "env": { "MCP_TERMINAL_DEFAULT_TIMEOUT": "30000" } }

代替手段との比較

機能	mcp-interactive-terminal	アプリ固有のターミナルサーバー	汎用シェル MCP サーバー
クロスプラットフォーム	はい	多くの場合、単一アプリのみ	さまざま
クリーンな出力（xterm-headless）	はい	いいえ（画面のスクレイピング）	いいえ（生の PTY ダンプ）
スマートな完了検出	4 層アルゴリズム	いいえ	基本的なタイムアウト
セキュリティ層	7 層（確認フロー、サンドボックス、編集など）	なし	基本的
危険なコマンドの確認	はい（独立したツール）	いいえ	いいえ
MCP ツールのアノテーション	はい	いいえ	いいえ
バックグラウンドセッション	はい	いいえ（アクティブなタブを使用）	はい
用途を絞った API	7 個のツール	2～3 個のツール	15～20 個以上のツール（機能範囲の拡大）
インストール	npx -y（設定不要）	特定のアプリが必要	さまざま

開発

git clone https://github.com/amol21p/mcp-interactive-terminal.git
cd mcp-interactive-terminal
npm install
npm run build
npm test

MCP Inspector でテストします。

npx @modelcontextprotocol/inspector dist/index.js

ライセンス

MIT