Interactive Shell MCP

TUIサポートを備えたインタラクティブなシェルセッション用のMCPサーバーです。AIエージェントに、永続的なターミナル、インタラクティブなプロンプト操作、レンダリングされた画面の読み取り、出力検索機能を提供します。

デモ

このツールの存在意義

ほとんどのAIコーディングツールは、シェルコマンドを分離して実行します。つまり、各コマンドが新しいシェルを起動するため、インタラクティブなプロンプトは使用できず、TUIアプリは生の制御コードを出力するだけです。このMCPサーバーは、仮想ターミナルエミュレーター（@xterm/headless）を備えた永続的なPTYセッションを提供します。これにより、エージェントはシェル状態を維持し、矢印キーでインタラクティブなプロンプトを操作し、レンダリングされたターミナル画面をクリーンなテキストとして読み取ることができます。

3つの出力モード:

クイックスタート

git clone https://github.com/lightos/interactive-shell-mcp.git
cd interactive-shell-mcp
npm install && npm run build
claude mcp add interactive-shell node dist/src/server.js

その後、Claudeに次のように尋ねてください: "htopを監視して、CPU使用率が最も高いものを教えて"

機能

• @xterm/headless を介したTUIアプリからのレンダリングされた画面読み取り

• すべての読み取りツールにわたる waitForIdle（sleepによる推測は不要）

• テキストおよび正規表現パターンマッチングによる画面検索

• 行/列座標を指定した矩形領域の抽出

• シェルの許可リスト: bash, zsh, fish, sh, dash, ksh, powershell.exe, pwsh, cmd.exe

• 10分間のアイドル後の自動クリーンアップ、プロセス終了後60秒間の終了コード検出

• クロスプラットフォーム: Unix/Linux/macOS + Windows

ユースケース

• インタラクティブなスキャフォールディングと移行: npx create-next-app, drizzle-kit push, prisma migrate, npm init、またはinquirer/clackベースのCLI

• システム監視: htop, btop, top, iftop, duf（プロセス検索と領域抽出付き）

• DevOps TUI: lazydocker, lazygit, k9s, terraform console

• リモートセッション: サーバーへの ssh（SSH経由のネストされたTUIアプリを含む）

• データベースCLI: psql, mysql, redis-cli, mongosh（インタラクティブモード）

• ネットワークツール: netcat/ncat, nmap, airodump-ng, tcpdump

• REPLとデバッガー: python, node, irb, gdb/lldb

• テキストエディタ: vim, nano, emacs -nw

MCP設定

Claude Code (CLI)

claude mcp add interactive-shell node /path/to/interactive-shell-mcp/dist/src/server.js

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) または %APPDATA%\Claude\claude_desktop_config.json (Windows) に追加してください:

{
  "mcpServers": {
    "interactive-shell": {
      "command": "node",
      "args": ["/path/to/interactive-shell-mcp/dist/src/server.js"]
    }
  }
}

VS Code / Cursor

MCP設定（.vscode/mcp.json または ~/.cursor/mcp.json）に追加してください:

{
  "mcpServers": {
    "interactive-shell": {
      "command": "node",
      "args": ["/path/to/interactive-shell-mcp/dist/src/server.js"]
    }
  }
}

ツールリファレンス

start_shell_session

仮想ターミナルエミュレーターを備えた新しいPTYシェルを起動します。

{ sessionId, cols, rows } を返します

send_shell_input

PTYに入力を書き込みます。デフォルトでキャリッジリターンが付加されます。

read_shell_output

PTYから出力を読み取ります。3つのモード: streaming（デフォルト）、snapshot、screen。

Screenモードは、メタデータ内にカーソル位置、ターミナル寸法、代替バッファ状態を返します。

get_screen_region

画面の矩形領域からテキストを抽出します。

get_screen_cursor

カーソル位置と現在の行のテキストを取得します。

{ cursor: { x, y }, currentLine, isAlternateBuffer } を返します

search_screen

ターミナル画面でテキストまたは正規表現を検索します。最大50件の結果を返します。

{ results: [{ row, col, text }], count } を返します

list_sessions

メタデータを含むすべてのアクティブなセッションを一覧表示します。パラメータなし。

{ sessions: [{ sessionId, shell, cols, rows, isAlternateBuffer, idleSeconds }] } を返します

resize_shell

アクティブなセッションのターミナルサイズを変更します。

end_shell_session

PTYを閉じ、リソースをクリーンアップします。

使用例

これらは、統合を構築する開発者向けのMCPツール呼び出しパターンを示しています。エンドユーザーはAIエージェントと自然に対話するだけです。

TUIアプリの読み取り

await send_shell_input(sessionId, "htop");
const { output, metadata } = await read_shell_output(sessionId, {
  mode: "screen",
  waitForIdle: 500
});
// output: rendered htop as clean text (CPU bars, process table, etc.)
// metadata.isAlternateBuffer: true (htop uses alternate screen)

// Extract just the process list (rows 6-30)
const processes = await get_screen_region(sessionId, {
  startRow: 6, startCol: 0, endRow: 30, endCol: 120,
  trimWhitespace: true
});

インタラクティブなプロンプトの操作

// Send arrow keys and enter in raw mode
await send_shell_input(sessionId, "\\x1b[B", { raw: true });  // down arrow
await send_shell_input(sessionId, " ", { raw: true });         // space to select
await send_shell_input(sessionId, "\\r", { raw: true });       // enter to confirm

// Read what the prompt looks like now
const screen = await read_shell_output(sessionId, {
  mode: "screen", waitForIdle: 300
});

コマンド出力の待機

await send_shell_input(sessionId, "npm install");
const output = await read_shell_output(sessionId, {
  waitForIdle: 1000  // wait for 1s of silence
});

コンテンツの検索

// Find all error lines
const errors = await search_screen(sessionId, {
  pattern: "error|Error|ERROR",
  regex: true,
  waitForIdle: 500
});
// [{ row: 12, col: 0, text: "Error" }, ...]

セッションの動作

• 自動クリーンアップ: 10分以上アイドル状態のセッションは自動的に破棄されます

• 終了検出: シェルが終了すると、ツールは汎用的な無効IDエラーの代わりに60秒間 "Session exited with code N" を返します

• シェル許可リスト: 既知のシェル（bash, zsh, fish, sh, dash, ksh, powershell.exe, pwsh, cmd.exe）のみ起動可能です。不明な値はプラットフォームのデフォルトにフォールバックします。

ライセンス

MIT