ssh-tmux MCP server
Commit Oct 3, 2026Manages persistent SSH sessions via tmux to allow AI agents to interact with remote terminals through visual snapshots.
Also known as devnullvoid/mcp-ssh-tmux
- Stars
- 7
- Tools
- 9
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 3, 2026
- License
- MIT
What is ssh-tmux MCP?
ssh-tmux manages persistent SSH sessions via tmux to allow AI agents to interact with remote terminals through visual snapshots. It exposes 9 tools, such as open_session, send_command, send_keys.
Summary generated from the project's README
About ssh-tmux MCP server
Managing persistent remote terminal sessions through visual snapshots is what this server enables for developers using AI agents. By utilizing a local tmux instance as a terminal multiplexer, the server allows an agent to interact with remote machines as if it were a human looking at a screen. This approach avoids the need for complex regex patterns to detect command completion because the agent interprets prompts and errors directly from the terminal output.
Users can set this up locally via uv or pip and connect it to clients like Claude Desktop or Cursor. The server maintains SSH connections in dedicated tmux windows, meaning sessions stay alive even if the client or the MCP server restarts. It uses ssh -G for reliable configuration resolution and operates on an isolated tmux socket named mcp-ssh to avoid interfering with personal sessions. The toolset includes functions for opening sessions, sending commands or raw keystrokes, capturing screen snapshots, and performing remote file transfers through dedicated read and write tools.
What you can do with it
- 1Monitor long-running remote processesAn AI agent can check the progress of a background build or download without terminating the task.
- 2Perform remote file operationsA developer can instruct an agent to read or modify configuration files on a remote server.
- 3Manually inspect agent activityA human user can attach to the specific tmux socket to watch the agent's terminal work in real-time.
- 4Handle interactive terminal inputsThe agent can send specific keystrokes like Ctrl+C to manage running processes.
Written from the project's README. Every use case is checked against a quote from it.
ssh-tmux MCP tools 9
Detected from the READMEopen_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 | — |
Configuration
FASTMCP_TRANSPORT
| Name | Description | |
|---|---|---|
| FASTMCP_TRANSPORT | — |
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachabledevnullvoid/mcp-ssh-tmux is public and reachablegithub.com/devnullvoid/mcp-ssh-tmux ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-03github.com/devnullvoid/mcp-ssh-tmux ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model9 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubmcp-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 questions
What tools does ssh-tmux MCP provide?
It exposes 9 tools, including open_session, send_command, send_keys, get_snapshot, read_remote_file.
How can I see what the agent is doing in real-time?
You can manually run a tmux command to attach to the dedicated socket and view the active sessions.
Do SSH connections stay active if the server restarts?
Yes, the connections are persistent because they are managed within a tmux instance.