tmux-mcp

tmux-mcp

AI アシスタントに tmux セッションの全容を提供する MCP サーバーです。セッション、ウィンドウ、ペインの一覧表示、ターミナル出力の読み取り、コマンドの送信ができます。

AI エージェントの作業をリアルタイムで確認できます。 TMUX_MCP_ALWAYS_USE を有効にすると、すべてのシェルコマンドを直接 Bash で実行する代わりに、名前付き tmux セッション経由で実行できます。AI が実行するコマンドはすべてターミナルにリアルタイムで表示され、完全に監査できます。

Claude Code、OpenCode、Cursor、Windsurf、および MCP 対応のあらゆるホストで動作します。

できること

ターミナルの状態を読み取る

• アクティブな tmux セッションをすべて一覧表示します。ウィンドウ数、作成時刻、接続状態も確認できます
• セッション内のウィンドウを一覧表示します。インデックス、名前、ペイン数、アクティブなウィンドウを確認できます
• ウィンドウ内のペインを一覧表示します。サイズ、実行中のコマンド、アクティブなペインを確認できます

画面の内容を確認する

• 任意のペインの表示中の出力を取得します。最大 5 000 行のスクロールバックに対応します
• ターミナル内のログ、コンパイラーエラー、サーバー出力、テスト実行など、あらゆる内容を読み取ります

作成と整理

• 作業ディレクトリと初期コマンドを指定して、セッション、ウィンドウ、ペインを作成します
• ペインを水平または垂直に分割します
• 確実に対象を指定できるよう、セッションとウィンドウの名前を変更します

クリーンアップ

• セッション、ウィンドウ、個々のペインを終了します

ペインを操作する

• 任意のペインにシェルコマンドを送信し、出力をすぐに読み取ります
• キーシーケンスをそのまま送信します。割り込みの C-c、終了の Escape、矢印キーなどに対応します
• 実行時間の長いコマンドが完了するまで待てるよう、出力を取得する前の待機時間を設定できます

エラーに安全に対処

• 対象が不正、または tmux サーバーがない場合でも、クラッシュする代わりに読みやすいエラーメッセージを返します

ツール

list_sessions

アクティブな tmux セッションをすべて一覧表示します。パラメーターはありません。

返される情報：セッション名、ウィンドウ数、作成時刻、接続／切断状態。

list_windows

セッション内のウィンドウを一覧表示します。

パラメーター	型	説明
session	string	セッション名（list_sessions で取得）

返される情報：ウィンドウのインデックス、名前、ペイン数、アクティブなウィンドウかどうか。

list_panes

セッションまたはウィンドウ内のペインを一覧表示します。

パラメーター	型	説明
target	string	セッション名（work）または session:window（work:0）

返される情報：ペインのインデックス、タイトル、サイズ（例：220x50）、アクティブかどうか、実行中のコマンド。

capture_pane

ペインの現在のターミナル出力を取得します。

パラメーター	型	デフォルト	説明
target	string	—	ペインの対象：session:window.pane（例：work:0.0）
lines	number	150	含めるスクロールバックの行数（最大 5000）

返される情報：画面に表示されているターミナルテキスト。

セキュリティに関する注意： ペインの出力には、ターミナルに表示された環境変数、API キー、トークン、認証情報が含まれる場合があります。このサーバーは、信頼できるローカル環境でのみ使用してください。

send_keys

ペインにコマンドまたはキーシーケンスを送信し、結果を取得します。

パラメーター	型	デフォルト	説明
target	string	—	ペインの対象：session:window.pane
keys	string	—	コマンドまたは tmux キー表記（C-c、Escape、Up など）
enter	boolean	true	キー送信後に Enter キーを押すかどうか
capture_lines	number	50	送信後に取得する行数
wait_ms	number	400	出力を取得する前の待機時間（ミリ秒）

返される情報：確認メッセージと、コマンド実行後のペイン出力。

new_session

切り離された状態の新しい tmux セッションを作成します。

パラメーター	型	説明
name	string	セッション名。省略すると、tmux が自動で割り当てます。
cwd	string	セッションの作業ディレクトリ。
command	string	最初のウィンドウでただちに実行するシェルコマンド。

new_window

既存のセッション内に新しいウィンドウを作成します。

パラメーター	型	説明
session	string	ウィンドウを作成するセッションです。
name	string	ウィンドウ名です。
cwd	string	新しいウィンドウの作業ディレクトリです。
command	string	直ちに実行するシェルコマンドです。

split_pane

ペインを2つに分割します。

パラメーター	型	デフォルト	説明
target	string	—	分割するペインまたはウィンドウ：session:window.pane
direction	horizontal | vertical	horizontal	horizontal = 左右に分割、vertical = 上下に分割
cwd	string	—	新しいペインの作業ディレクトリです。
command	string	—	新しいペインで実行するシェルコマンドです。
size	number	—	新しいペインのサイズ（パーセント、1～99）です。

kill_session

セッションと、そのすべてのウィンドウおよびペインを終了します。破壊的な操作です。元に戻せません。

パラメーター	型	説明
session	string	終了するセッション名です。

kill_window

ウィンドウと、そのすべてのペインを終了します。破壊的な操作です。

パラメーター	型	説明
target	string	ウィンドウのターゲット：session:window

kill_pane

単一のペインと、その実行中のプロセスを終了します。破壊的な操作です。

パラメーター	型	説明
target	string	ペインのターゲット：session:window.pane

rename_session

パラメーター	型	説明
session	string	現在のセッション名です。
new_name	string	新しい名前です。

rename_window

パラメーター	型	説明
target	string	ウィンドウのターゲット：session:window
new_name	string	新しい名前です。

ターゲットの形式

すべてのツールでは、tmux 標準の session:window.pane 表記を使用します。

work           →  session named "work"
work:0         →  window 0 of session "work"
work:0.0       →  pane 0, window 0, session "work"
work:editor.1  →  pane 1 of window named "editor" in session "work"

capture_pane または send_keys を呼び出す前に、list_sessions → list_windows → list_panes の順に使って適切なターゲットを確認してください。

インストール

npm install -g @fr1sk/tmux-mcp

設定

OpenCode (~/.config/opencode/opencode.json)

{
  "mcp": {
    "tmux": {
      "type": "local",
      "command": ["tmux-mcp"]
    }
  }
}

Claude Code (~/.claude/settings.json)

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

Cursor / Windsurf (mcp.json)

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

使用例

What tmux sessions do I have running?

Show me the output of my dev server — it's in the work session

My tests are failing, check what's in work:1.0

Run git status in my work session and show me the output

Send Ctrl-C to work:0.0, the process is stuck

Tail the last 300 lines from the logs pane in my api session

Create a new session called 'dev' in ~/Projects/myapp and run npm run dev

Split work:0.0 vertically and run npm test in the new pane

Rename session 'new' to 'api'

Kill the old session named 'temp'

環境変数

エージェントの動作を制御するには、MCP クライアントの設定の environment に以下を設定します。

変数	デフォルト	説明
TMUX_MCP_DEFAULT_SESSION	—	alwaysUseTmux が有効なときに、エージェントがコマンドの送信先とするセッション名です
TMUX_MCP_ALWAYS_USE	false	"true" に設定すると、すべてのシェルコマンドを直接 Bash で実行する代わりに tmux 経由で送信します

両方が設定されている場合、get_config ツールは instructions フィールドを返します。エージェントはこのフィールドを使って、設定されたセッション内の send_keys 経由ですべてのシェルコマンドを自動的に送信します。

例（OpenCode）：

{
  "mcp": {
    "tmux": {
      "type": "local",
      "command": ["tmux-mcp"],
      "environment": {
        "TMUX_MCP_ALWAYS_USE": "true",
        "TMUX_MCP_DEFAULT_SESSION": "dev"
      }
    }
  }
}

セキュリティ

このサーバーは、tmux 経由で制限のないローカルシェルアクセスを提供します。

• capture_pane — 生のターミナル出力を返します。ターミナルに表示されていた場合、環境変数、API キー、トークン、データベースのパスワード、SSH 秘密鍵が含まれることがあります。
• send_keys — ターゲットのペインで任意のシェルコマンドを実行します。AI が送信するコマンドは、すべてユーザーの権限でシェル内で実行されます。
• new_session、new_window、split_pane の command パラメーター — tmux に直接渡され、tmux は $SHELL -c 経由で実行します。検証もサンドボックス化も行われません。

このサーバーは、信頼できるローカル開発環境でのみ使用してください。ネットワークからアクセス可能な MCP ホストや、信頼できない AI アシスタントに決して公開しないでください。

要件

• Node.js 18+
• $PATH 上に tmux があること