ssh-tmux MCPサーバー
コミット 2026年10月3日tmuxを介して永続的なSSHセッションを管理し、AIエージェントが視覚的なスナップショットを通じてリモートターミナルと対話できるようにします。
別名 devnullvoid/mcp-ssh-tmux
- スター
- 7
- ツール
- 9
- ダウンロード数(30日間)
- —
- 最新バージョン
- —
- 最終コミット
- 2026年10月3日
- ライセンス
- MIT
ssh-tmux MCPとは
ssh-tmuxはMCPサーバーです。 tmuxを介して永続的なSSHセッションを管理し、AIエージェントが視覚的なスナップショットを通じてリモートターミナルと対話できるようにします。. 9個のツールを提供しており、open_session, send_command, send_keysなどがあります。
プロジェクトのREADMEから生成された概要
ssh-tmux MCP server について
このMCP serverは、AIエージェントを使用する開発者向けに、視覚的なスナップショットを通じた永続的なリモートターミナルセッションの管理を可能にします。ローカルのtmuxインスタンスをターミナルマルチプレクサとして活用することで、エージェントがまるで人間が画面を見ているかのようにリモートマシンと対話できるようになります。このアプローチでは、エージェントがターミナル出力からプロンプトやエラーを直接解釈するため、コマンドの完了を検知するための複雑な正規表現パターンは必要ありません。
ユーザーはuvまたはpipを使用してローカルにセットアップし、Claude DesktopやCursorなどのクライアントに接続できます。このサーバーは専用のtmuxウィンドウ内でSSH接続を維持するため、クライアントやMCP serverが再起動してもセッションは維持されます。設定の解決には信頼性の高いssh -Gを使用し、個人のセッションへの干渉を避けるためにmcp-sshという名前の隔離されたtmuxソケットで動作します。ツールセットには、セッションの開始、コマンドや生のキーストロークの送信、画面スナップショットの取得、および専用の読み取り・書き込みツールによるリモートファイル転送の機能が含まれています。
できること
- 1長時間実行されるリモートプロセスの監視AIエージェントは、タスクを終了させることなく、バックグラウンドでのビルドやダウンロードの進捗を確認できます。
- 2リモートファイル操作の実行開発者はエージェントに対し、リモートサーバー上の設定ファイルを読み取ったり、変更したりするように指示できます。
- 3エージェントのアクティビティを手動で確認人間のユーザーが特定のtmuxソケットにアタッチすることで、エージェントのターミナル作業をリアルタイムで監視できます。
- 4対話的なターミナル入力の処理エージェントは、実行中のプロセスを管理するためにCtrl+Cなどの特定のキーストロークを送信できます。
プロジェクトの README から作成されています。すべてのユースケースは、その引用と照らし合わせて確認されています。
ssh-tmux MCPツール 9
READMEから検出open_sessionsend_commandsend_keysget_snapshotread_remote_filewrite_remote_filelist_sessionscleanup_dead_sessionsclose_session
| open_session | — | |
| send_command | — | |
| send_keys | — | |
| get_snapshot | — | |
| read_remote_file | — | |
| write_remote_file | — | |
| list_sessions | — | |
| cleanup_dead_sessions | — | |
| close_session | — |
設定
FASTMCP_TRANSPORT
| 名前 | 説明 | 種類 |
|---|---|---|
| FASTMCP_TRANSPORT | — |
自動チェック
実行日 2026年11月14日完全なレポート →まだ検証されていません。サーバーには80点のスコア、重大な問題がないこと、および検証に必要な十分なデータが必要です。 チェックの仕組み · 点数を上げるための改善点
- ソースリポジトリがリンクされており、アクセス可能devnullvoid/mcp-ssh-tmux is public and reachablegithub.com/devnullvoid/mcp-ssh-tmux ↗合格
- パッケージがこのリポジトリをソースとして指定未チェック
- ビルドの来歴 (Sigstore 証明)未チェック
- オープンソースライセンス (OSI)MITspdx.org/licenses/MIT.html ↗合格
- 過去1年以内にコミットまたはリリースありLast commit or release 2026-10-03github.com/devnullvoid/mcp-ssh-tmux ↗合格
- OpenSSF Scorecard未チェック
- パッケージ名が有名なパッケージに酷似していない未チェック
- パッケージおよびその依存関係に重大な勧告なし未チェック
- モデルへの隠れた指示がない9 tool descriptions and the README read; no override phrases, credential paths or hidden characters合格
- 破壊的なツールがラベル付けされているNo tool named like delete, drop or exec合格
- リモートエンドポイントが MCP ハンドシェイクに応答未チェック
README
GitHubで見るmcp-ssh-tmux
A high-performance, persistent Model Context Protocol (MCP) server that manages SSH sessions via a local tmux instance.
Why this exists?
Traditional SSH automation runs individual commands without state tracking between executions. Other implementations rely on complex regex patterns to detect command completion. By using tmux as a persistent terminal multiplexer, this project eliminates that complexity entirely. The AI agent simply "looks" at the screen like a human would - the server provides visual snapshots, and the agent interprets prompts, errors, and output naturally.
Key Features
- Persistence: SSH connections stay alive in
tmuxeven if the MCP server or your AI client restarts. - Observability: You can manually run
tmux -L mcp-ssh ato see exactly what the agent is doing in real-time. - Isolation: Runs on its own dedicated tmux socket (
mcp-ssh), completely isolated from your personal tmux sessions. - Reliability: Uses
ssh -Gfor robust config resolution (handles aliases, identity files, etc.). - Safety: Built-in command validation to prevent common dangerous operations.
- File Transfer: Native tools for reading and writing remote files. Reads prefer a full-file SSH transfer and fall back to the existing PTY when needed.
Installation
Requirements
- tmux must be installed on your system
- Ubuntu/Debian:
apt install tmux - macOS:
brew install tmux - Arch:
pacman -S tmux
- Ubuntu/Debian:
Via uv (Recommended)
uv tool install mcp-ssh-tmux
Via pip
pip install mcp-ssh-tmux
Configuration
Add this to your mcp.json (e.g., in Claude Desktop, Cursor, or 1mcp):
{
"mcpServers": {
"ssh-tmux": {
"command": "uv",
"args": [
"run",
"mcp-ssh-tmux"
]
}
}
}
Note: If you installed via uv tool install, you can just use mcp-ssh-tmux as the command.
Tools
open_session(host, username, port): Opens a new SSH connection in a unique tmux window.send_command(session_id, command, lines, timeout): Sends a command and polls for a prompt/output. Returns only the lastlinesof terminal output/scrollback.timeout(default 2.0s) controls how long to wait — increase for slower commands like package installs.send_keys(session_id, keys): Sends raw keystrokes without Enter. Use for Ctrl+C, Ctrl+D, interactive input, etc.get_snapshot(session_id, lines): Captures the current screen state. Returns only the lastlinesof terminal output/scrollback.read_remote_file(session_id, remote_path, fallback_lines): Reads a remote text file. Prefer this overcatviasend_command()when you need the full file contents.fallback_linescontrols bounded tmux-history capture if direct SSH read is unavailable.write_remote_file(session_id, remote_path, content, append): Writes content to a remote file.list_sessions(): Lists all active SSH windows.cleanup_dead_sessions(max_age_seconds): Kills all windows where the SSH connection has closed. Optionally filters by how long the session has been dead.close_session(session_id): Kills the window and cleans up. WARNING: This terminates any running processes in the session. For long-running tasks, leave the session open and monitor withget_snapshot().
Transport Modes
By default, the server uses stdio for communication with MCP clients. You can switch to the modern Streamable HTTP transport using environment variables:
# Start server in HTTP mode on port 8080
FASTMCP_TRANSPORT=http FASTMCP_PORT=8080 mcp-ssh-tmux
The server will be available at http://localhost:8080/mcp.
Important Notes
Automatic Cleanup
- Background Reaper: The server automatically cleans up sessions that have been dead (disconnected) for more than 24 hours.
- Manual Cleanup: Use
cleanup_dead_sessions()to manually clear disconnected sessions at any time.
Reading Files
- Use
read_remote_file()for file contents:send_command("cat ...")andget_snapshot()are screen/snapshot tools, so they only return the tail of terminal output. linescontrols snapshot depth: Increaselinesonsend_command()orget_snapshot()when you need more terminal history, but useread_remote_file()for actual file reads.fallback_linescontrols PTY fallback depth: If direct SSH file read is unavailable,read_remote_file()inspects only the lastfallback_linesof tmux history. Increase it when needed, but keep it bounded.- Best for text files:
read_remote_file()is intended for configs, source, logs, and similar text content.
Session Management
- Do not close sessions with active processes: Closing a session terminates all running commands (builds, downloads, etc.)
- Monitor long-running tasks: Use
get_snapshot()to check progress without closing the session - Sessions persist: SSH connections remain alive in tmux even if the MCP server restarts
- Isolated Tmux Socket: The server runs its own tmux server on a separate socket (
mcp-ssh) to prevent interfering with your personal tmux sessions. - Manual inspection: To manually connect to the MCP tool's tmux session, you must use the
-Lflag and specify the socket:tmux -L mcp-ssh a # or tmux -L mcp-ssh attach -t mcp-ssh
Acknowledgments
Built with FastMCP and libtmux.
Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
Star History
If you find this project useful, please consider giving it a star! ⭐
License
MIT
ssh-tmux MCPのよくある質問
ssh-tmux MCPが提供するツールは
9個のツールを提供しており、open_session, send_command, send_keys, get_snapshot, read_remote_fileなどがあります。
エージェントが何をしているのかをリアルタイムで確認するにはどうすればよいですか?
専用のソケットにアタッチするためのtmuxコマンドを手動で実行することで、アクティブなセッションを確認できます。
サーバーが再起動してもSSH接続は維持されますか?
はい、接続はtmuxインスタンス内で管理されているため、永続的に維持されます。