Terminal MCP

公式

AIアシスタントに、ターミナルセッションの共有ライブビューを提供し、CLIやTUIのデバッグ、または自律的なターミナル制御を可能にします。

GitHub

132

このMCPを試すスポンサー

Terminal MCPで何ができますか？

コマンド入力とキー送信 — AIにtypeとsendKeyを使ってシェルコマンドを実行させます。EnterやCtrl+Cなどの特殊キーも含みます。
ターミナル出力の読み取り — getContentで現在のターミナルバッファをプレーンテキストとして取得するか、takeScreenshotでtext、ansi、png形式のスクリーンショットを取得します。
セッションの記録と再生 — startRecordingとstopRecordingでasciicast v2の録画を開始・停止し、asciinemaで再生します。
複数セッションの管理 — createSessionで独立したターミナルセッションを作成し、listSessionsでアクティブなセッションを一覧表示し、destroySessionでクリーンアップします。各セッションはsessionIdで識別されます。

ドキュメント

AIにあなたのターミナルを見せ、操作させましょう。

Terminal MCPは、LLMにターミナルセッションの共有ビューを提供します。CLIやTUIアプリケーションのリアルタイムデバッグや、AIによるターミナルベースのツールの自律操作に最適です。

インストール

npm install -g @ellery/terminal-mcp

または、インストールスクリプトを使用:

curl -fsSL https://raw.githubusercontent.com/elleryfamilia/terminal-mcp/main/install.sh | bash

AIツールの設定

terminal-mcpを、マシンにインストールされているすべてのAIツールのMCP設定に一括で組み込みます:

terminal-mcp setup                      # detect & install for all detected tools
terminal-mcp setup --dry-run            # preview without writing
terminal-mcp setup --client claude-code,gemini   # specific tools only
terminal-mcp setup --uninstall          # remove the entry from each tool

対応クライアント（各クライアントの設定形式に応じた正しいスキーマが適用されます）:

クライアント	設定ファイル	形式
OpenAI Codex CLI	`~/.codex/config.toml`	TOML
GitHub Copilot CLI	`~/.copilot/mcp-config.json`	JSON
Gemini CLI	`~/.gemini/settings.json`	JSON
OpenCode	`~/.config/opencode/opencode.json`	JSON
Claude Code	`~/.claude.json`	JSON
Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) / `%APPDATA%\Claude\claude_desktop_config.json` (Windows)	JSON

初回インストール時、既存設定の.bakが元のファイルの隣に書き出されます。terminal-mcpエントリは、他のサーバーや無関係なキーを妨げずに追加されます。setupを再度実行しても何も変更されません。

アップグレード

npm install -g @ellery/terminal-mcp@latest

対話モードでは、新しいリリースが利用可能な場合、次回起動時にバナーが表示されます。terminal-mcpはnpmレジストリを1日1回チェックし、結果をキャッシュします。ヘッドレスモードとMCPクライアントモードでは、チェックや表示は一切行われません（MCP stdioはクリーンな状態が保たれます）。完全に無効にするには、NO_UPDATE_NOTIFIER=1を設定するか、--no-update-notifierを渡します。

機能

完全なターミナルエミュレーション: xterm.jsヘッドレスを使用し、正確なVT100/ANSIエミュレーションを実現
クロスプラットフォームPTY: node-ptyによるネイティブな擬似ターミナルサポート（macOS、Linux、Windows）
MCPプロトコル: AIアシスタント統合のためのModel Context Protocolを実装
セッション録画: ターミナルセッションをasciicast形式で録画し、asciinemaで再生可能
シンプルなAPI: 入力、観察、録画、セッションライフサイクルをカバーする9つのツール
ヘッドレスモード: TTYなしでスタンドアロンのMCPサーバーとして実行 — CI、コンテナ、非対話環境に最適
マルチセッション: 1つのプロセスで複数の独立したターミナルセッションを実行し、sessionIdで識別
サンドボックスモード: ファイルシステムとネットワークアクセスに対するオプションのセキュリティ制限

ソースからのビルド

npm install
npm run build

使用方法

MCP設定

MCPクライアント設定に追加:

{
  "mcpServers": {
    "terminal": {
      "command": "terminal-mcp"
    }
  }
}

カスタムオプション付き:

{
  "mcpServers": {
    "terminal": {
      "command": "terminal-mcp",
      "args": ["--cols", "100", "--rows", "30", "--shell", "/bin/zsh"]
    }
  }
}

コマンドラインオプション

terminal-mcp [OPTIONS]

Options:
  --cols <number>        Terminal width in columns (default: 120)
  --rows <number>        Terminal height in rows (default: 40)
  --shell <path>         Shell to use (default: $SHELL or bash)
  --headless             Run in headless mode (embedded PTY + MCP over stdio, no TTY needed)
  --sandbox              Enable sandbox mode (restricts filesystem/network)
  --sandbox-config <path> Load sandbox config from JSON file
  --version, -v          Show version number
  --help, -h             Show help message

Recording Options:
  --record [mode]     Enable recording (default mode: always)
                      Modes: always, on-failure, off
  --record-dir <dir>  Recording output directory
                      (default: ~/.local/state/terminal-mcp/recordings)
  --idle-time-limit <sec>   Max idle time between events (default: 2s)
  --max-duration <sec>      Max recording duration (default: 3600s)
  --inactivity-timeout <sec>  Stop after no output (default: 600s)

Multi-Session Options:
  --max-sessions <n>           Max concurrent sessions (default: 5)
  --session-idle-timeout <sec> Idle non-default sessions are auto-destroyed
                               after this period (default: 600s)

ヘッドレスモード

デフォルトでは、Terminal MCPはデュアルプロセスアーキテクチャを使用します。対話型ターミナルでterminal-mcpを実行し（Unixソケットを作成）、MCPクライアントがそのソケットに接続する2番目のインスタンスを起動します。これにはTTYが必要です。

ヘッドレスモード（--headless）は、内部に埋め込みPTYを生成し、単一プロセスでMCPをstdio経由で直接提供することで、この要件を排除します。対話型ターミナルセッションもソケットも不要で、組み込みターミナルを備えた自己完結型のMCPサーバーです。

ヘッドレスモードを使用する場合

CI/CDパイプライン — TTYが利用できない
Dockerコンテナ — 並行して実行する対話型シェルがない
リモート/クラウド環境 — 自動化によって生成されたMCPサーバー
簡素化されたセットアップ — 単一プロセス、ソケット調整不要

設定

{
  "mcpServers": {
    "terminal": {
      "command": "terminal-mcp",
      "args": ["--headless", "--cols", "120", "--rows", "40"]
    }
  }
}

仕組み

MCP Client (Claude Code, etc.)
    │ STDIO (JSON-RPC)
    ▼
terminal-mcp --headless
    ├── MCP Server (stdio transport)
    ├── Terminal Emulator (@xterm/headless)
    └── Embedded PTY (node-pty)
            │
            ▼
        Shell Process (bash, zsh, etc.)

ヘッドレスモードでは、ターミナルセッションは起動時に即座に初期化されるため、すべてのツール（type、sendKey、getContent、takeScreenshot、startRecording、stopRecording、createSession、listSessions、destroySession）がすぐに利用可能です。

MCPツール

すべての入出力ツール（type、sendKey、getContent、takeScreenshot）は、オプションのsessionId引数を受け付けます。省略するとデフォルトセッションを対象とし、createSessionが返すIDを渡すと特定のセッションを操作できます。

`type`

ターミナルにテキスト入力を送信します。

{
  "name": "type",
  "arguments": {
    "text": "echo hello"
  }
}

`sendKey`

特殊キーまたはキーの組み合わせを送信します。

{
  "name": "sendKey",
  "arguments": {
    "key": "Enter"
  }
}

サポートされているキー:

基本: Enter、Tab、Escape、Backspace、Delete
矢印: ArrowUp、ArrowDown、ArrowLeft、ArrowRight
ナビゲーション: Home、End、PageUp、PageDown、Insert
ファンクション: F1からF12まで
コントロール: Ctrl+AからCtrl+Zまで、Ctrl+C、Ctrl+Dなど

`getContent`

ターミナルバッファをプレーンテキストとして取得します。

{
  "name": "getContent",
  "arguments": {
    "visibleOnly": false
  }
}

`takeScreenshot`

ターミナルの状態をキャプチャします。3つの出力形式をサポート:

形式	説明
`text` (デフォルト)	プレーンテキストコンテンツ、カーソル位置、寸法を含むJSON
`ansi`	コンテンツフィールドにANSIカラーエスケープシーケンスを保持したJSON
`png`	PNG画像としてのカラースクリーンショット（`@resvg/resvg-js`が必要）

{
  "name": "takeScreenshot",
  "arguments": { "format": "text" }
}

ansi形式は、ターミナルのセルバッファからSGRエスケープシーケンスを再構築し、16色、256色、24ビットトゥルーカラーの属性と、太字、暗色、斜体、下線のスタイルを保持します。

png形式は、base64エンコードされたPNGデータを含むMCP imageコンテンツブロックを返します。One DarkカラーテーマとmacOSスタイルのウィンドウクロームでレンダリングされます。

`startRecording`

ターミナル出力のasciicast v2ファイルへの録画を開始します。

{
  "name": "startRecording",
  "arguments": {
    "mode": "always",
    "idleTimeLimit": 2,
    "maxDuration": 3600
  }
}

オプション:

mode: always（すべて保存）またはon-failure（非ゼロ終了コードの場合のみ保存）
outputDir: カスタム出力ディレクトリ
idleTimeLimit: イベント間の最大秒数（再生時の一時停止を制限）
maxDuration: N秒後に自動停止
inactivityTimeout: 出力がN秒間ない場合に自動停止

`stopRecording`

録画を停止し、asciicastファイルを確定します。

{
  "name": "stopRecording",
  "arguments": {
    "recordingId": "abc123"
  }
}

`createSession`

新しいターミナルセッションを作成し、そのメタデータを返します。返されたsessionIdを使用して、後続のツール呼び出しでこのセッションを対象にします。

{
  "name": "createSession",
  "arguments": {
    "shell": "/bin/zsh",
    "cols": 100,
    "rows": 30
  }
}

すべての引数はオプションです。戻り値:

{
  "sessionId": "3029d",
  "shell": "/bin/zsh",
  "cols": 100,
  "rows": 30,
  "createdAt": "2026-04-25T12:58:01.072Z",
  "lastActivityAt": "2026-04-25T12:58:01.072Z",
  "isDefault": false
}

`listSessions`

デフォルトを含むすべてのアクティブなセッションを一覧表示します。設定された制限も報告します。

{ "name": "listSessions", "arguments": {} }

`destroySession`

IDでセッションを破棄します。デフォルトセッションは破棄できません。

{
  "name": "destroySession",
  "arguments": { "sessionId": "3029d" }
}

マルチセッション

デフォルトでは、sessionIdなしのすべてのツール呼び出しは、自動作成された単一のデフォルトセッションを対象とします。これは、これまでのプロジェクトの動作と同じです。sessionIdを渡すと、1つのプロセスから複数の独立したPTYを操作できます。

デフォルトセッションは最初の使用時に作成され、破棄できません。
追加セッションはcreateSessionによって作成され、破棄されるかアイドル状態で追い出されるまで追跡されます（--session-idle-timeout、デフォルト600秒）。
同時セッション数は--max-sessions（デフォルト5）に制限されます。
アクティブな録画は、プロセス内のすべてのセッションからの出力をキャプチャします。

典型的なユースケース: AIエージェントが、あるセッションで長時間実行されるビルドを実行しながら、別のセッションで診断を実行し、コマンドのインターリーブを防ぎます。

サンドボックスモード

ファイルシステムとネットワークアクセスを制限してターミナルを実行:

# Interactive permission configuration
terminal-mcp --sandbox

# With a config file
terminal-mcp --sandbox --sandbox-config ~/.terminal-mcp-sandbox.json

対話モードでは、権限を設定するためのTUIダイアログが表示されます:

Sandbox Permissions Dialog

- **読み取り/書き込み**: フルアクセス（現在のディレクトリ、/tmp、キャッシュ） - **読み取り専用**: 読み取りは可能だが変更は不可（ホームディレクトリ） - **ブロック**: アクセス不可（SSHキー、クラウド認証情報、認証トークン）

設定ファイルの例:

{
  "filesystem": {
    "readWrite": [".", "/tmp", "~/.cache"],
    "readOnly": ["~"],
    "blocked": ["~/.ssh", "~/.aws", "~/.gnupg"]
  },
  "network": {
    "mode": "all"
  }
}

プラットフォームサポート:

macOS: sandbox-exec（Seatbelt）による完全サポート
Linux: bubblewrapによる完全サポート（bwrapのインストールが必要）
Windows: グレースフルフォールバック（サンドボックスなしで実行）

詳細な設定オプションについては、サンドボックスドキュメントを参照してください。

録画

Terminal MCPは、asciinemaで再生可能なasciicast v2形式でセッションを録画できます。

クイックスタート

# Start with recording enabled
terminal-mcp --record

# Run your commands, then exit
exit

# Output shows the saved file path:
# Recordings saved:
#   ~/.local/state/terminal-mcp/recordings/20240115_143022.cast
#
# Play with: asciinema play <file>

再生

録画を再生するにはasciinemaをインストール:

# macOS
brew install asciinema

# Linux/pip
pip install asciinema

# Play a recording
asciinema play ~/.local/state/terminal-mcp/recordings/20240115_143022.cast

# Play at 2x speed
asciinema play -s 2 recording.cast

録画モード

always（デフォルト）: すべての録画を保存
on-failure: セッションが非ゼロの終了コードで終了した場合のみ保存（失敗したCI実行のデバッグに便利）

# Only save recordings when something fails
terminal-mcp --record=on-failure

MCPツールによる録画

AIアシスタントは、MCPツールを介してプログラムで録画を制御することもできます:

startRecordingを呼び出してキャプチャを開始
ターミナル操作を実行
stopRecordingを呼び出して確定して保存

これにより、「このデバッグセッションを録画」や「このデモをキャプチャ」などのAI駆動ワークフローが可能になります。

アーキテクチャ

Terminal MCPには3つの動作モードがあります:

モード	フラグ	標準入力	説明
対話型	(デフォルト)	TTY	ユーザーはシェルを取得。AIはUnixソケット経由で接続
クライアント	(デフォルト)	非TTY	対話型セッションのソケットに接続し、stdio経由でMCPを提供
ヘッドレス	`--headless`	任意	自己完結型: 埋め込みPTY + stdio経由のMCPサーバー

ヘッドレスモード（MCP設定に推奨）

MCP Client (Claude Code, etc.)
    │ STDIO (JSON-RPC)
    ▼
terminal-mcp --headless
    ├── MCP SDK (@modelcontextprotocol/sdk)
    ├── Terminal Emulator (@xterm/headless)
    └── Embedded PTY (node-pty)
            │
            ▼
        Shell Process (bash, zsh, etc.)

対話型 + クライアントモード（2プロセス）

terminal-mcp (interactive, in your terminal)
    ├── User shell (stdin/stdout)
    └── Unix socket server (/tmp/terminal-mcp.sock)
            ▲
            │ JSON-RPC over socket
            ▼
terminal-mcp (client, spawned by MCP client)
    └── MCP server (stdio transport)

セッション例

# Type a command
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"type","arguments":{"text":"ls -la"}}}

# Send Enter key
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"sendKey","arguments":{"key":"Enter"}}}

# Get the output
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"getContent","arguments":{}}}

開発

npm run build    # Compile TypeScript
npm run dev      # Run with tsx (development)

ドキュメント

詳細なドキュメントについては、docsフォルダを参照してください:

要件

Node.js 18.0.0以降
Windows 10バージョン1809以降（ConPTYサポート用）

ライセンス

MIT