ssh-tmux MCP server
Commit 3. Okt. 2026Verwaltet persistente SSH-Sessions via tmux, damit KI-Agenten über visuelle Snapshots mit Remote-Terminals interagieren können.
Auch bekannt als devnullvoid/mcp-ssh-tmux
- Stars
- 7
- Tools
- 9
- Downloads, 30 Tage
- —
- Neueste Version
- —
- Letzter Commit
- 3. Okt. 2026
- Lizenz
- MIT
Was ist ssh-tmux MCP?
ssh-tmux ist ein MCP server. Verwaltet persistente SSH-Sessions via tmux, damit KI-Agenten über visuelle Snapshots mit Remote-Terminals interagieren können. Er stellt 9 Tools bereit, etwa open_session, send_command, send_keys.
Zusammenfassung generiert aus dem README des Projekts
Über ssh-tmux MCP server
Dieser Server ermöglicht es Entwicklern, die mit KI-Agenten arbeiten, persistente Remote-Terminal-Sessions über visuelle Snapshots zu verwalten. Durch die Nutzung einer lokalen tmux-Instanz als Terminal-Multiplexer erlaubt der Server einem Agenten, mit Remote-Maschinen so zu interagieren, als würde ein Mensch direkt auf einen Bildschirm schauen. Dieser Ansatz macht komplexe Regex-Patterns zur Erkennung von Befehlsvollendungen überflüssig, da der Agent Prompts und Fehler direkt aus der Terminalausgabe interpretiert.
Nutzer können dies lokal via uv oder pip einrichten und mit Clients wie Claude Desktop oder Cursor verbinden. Der Server hält die SSH-Verbindungen in dedizierten tmux-Windows aufrecht, was bedeutet, dass die Sessions aktiv bleiben, selbst wenn der Client oder der MCP server neu startet. Er nutzt ssh -G für eine zuverlässige Konfigurationsauflösung und arbeitet auf einem isolierten tmux-Socket namens mcp-ssh, um Konflikte mit persönlichen Sessions zu vermeiden. Das Toolset umfasst Funktionen zum Öffnen von Sessions, zum Senden von Befehlen oder Raw-Keystrokes, zum Erstellen von Screen-Snapshots sowie zum Durchführen von Remote-Dateiübertragungen über dedizierte Read- und Write-Tools.
Was du damit machen kannst
- 1Überwachung von langlaufenden Remote-ProzessenEin KI-Agent kann den Fortschritt eines Hintergrund-Builds oder Downloads prüfen, ohne die Aufgabe zu unterbrechen.
- 2Durchführung von Remote-DateioperationenEin Entwickler kann einen Agenten anweisen, Konfigurationsdateien auf einem Remote-Server zu lesen oder zu modifizieren.
- 3Manuelle Inspektion der Agenten-AktivitätEin menschlicher Nutzer kann sich mit dem spezifischen tmux-Socket verbinden, um die Terminal-Arbeit des Agenten in Echtzeit zu verfolgen.
- 4Handhabung von interaktiven Terminal-InputsDer Agent kann spezifische Keystrokes wie Ctrl+C senden, um laufende Prozesse zu steuern.
Geschrieben aus dem README des Projekts. Jeder Use Case wurde gegen ein Zitat daraus geprüft.
ssh-tmux MCP tools 9
Erkannt aus dem 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 | — |
Konfiguration
FASTMCP_TRANSPORT
| Name | Beschreibung | Typ |
|---|---|---|
| FASTMCP_TRANSPORT | — |
Automatisierte Checks
Geluften am 14. Nov. 2026Vollständiger Bericht →Noch nicht verifiziert. Ein Server benötigt einen Score von 80, keine kritischen Befunde und genug Daten für unsere Prüfung. Wie die Checks funktionieren · Was du für mehr Punkte verbessern kannst
- Source Repository verknüpft und erreichbardevnullvoid/mcp-ssh-tmux is public and reachablegithub.com/devnullvoid/mcp-ssh-tmux ↗Bestanden
- Paket nennt dieses Repository als QuelleNicht geprüft
- Build-Provenienz (Sigstore-Attestierung)Nicht geprüft
- Open Source Lizenz (OSI)MITspdx.org/licenses/MIT.html ↗Bestanden
- Commit oder Release im letzten JahrLast commit or release 2026-10-03github.com/devnullvoid/mcp-ssh-tmux ↗Bestanden
- OpenSSF ScorecardNicht geprüft
- Package-Name ähnelt keinem populären PackageNicht geprüft
- Keine kritischen Advisories im Paket oder seinen AbhängigkeitenNicht geprüft
- Keine versteckten Anweisungen an das Modell9 tool descriptions and the README read; no override phrases, credential paths or hidden charactersBestanden
- Destruktive Tools sind markiertNo tool named like delete, drop or execBestanden
- Remote-Endpoint beantwortet den MCP-HandshakeNicht geprüft
README
Auf GitHub ansehenmcp-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 Fragen
Welche Tools bietet ssh-tmux MCP?
Er stellt 9 Tools bereit, darunter open_session, send_command, send_keys, get_snapshot, read_remote_file.
Wie kann ich in Echtzeit sehen, was der Agent gerade macht?
Du kannst manuell einen tmux-Befehl ausführen, um dich mit dem dedizierten Socket zu verbinden und die aktiven Sessions einzusehen.
Bleiben SSH-Verbindungen aktiv, wenn der Server neu startet?
Ja, die Verbindungen sind persistent, da sie innerhalb einer tmux-Instanz verwaltet werden.