Serveur MCP ssh-tmux
Commit 3 oct. 2026Gère des sessions SSH persistantes via tmux pour permettre aux agents IA d'interagir avec des terminaux distants grâce à des captures d'écran visuelles.
Aussi connu sous devnullvoid/mcp-ssh-tmux
- Étoiles
- 7
- Outils
- 9
- Téléchargements, 30 jours
- —
- Dernière version
- —
- Dernier commit
- 3 oct. 2026
- Licence
- MIT
Qu'est-ce que ssh-tmux MCP ?
ssh-tmux est un serveur MCP. Gère des sessions SSH persistantes via tmux pour permettre aux agents IA d'interagir avec des terminaux distants grâce à des captures d'écran visuelles. Il expose 9 outils, comme open_session, send_command, send_keys.
Résumé généré à partir du README du projet
À propos du MCP server ssh-tmux
Ce serveur permet aux développeurs utilisant des agents IA de gérer des sessions de terminaux distants persistantes via des captures d'écran visuelles. En utilisant une instance tmux locale comme multiplexeur de terminaux, le serveur permet à un agent d'interagir avec des machines distantes comme s'il s'agissait d'un humain regardant un écran. Cette approche évite d'avoir recours à des patterns regex complexes pour détecter la fin d'une commande, car l'agent interprète les prompts et les erreurs directement depuis la sortie du terminal.
Les utilisateurs peuvent l'installer localement via uv ou pip et le connecter à des clients comme Claude Desktop ou Cursor. Le serveur maintient les connexions SSH dans des fenêtres tmux dédiées, ce qui signifie que les sessions restent actives même si le client ou le MCP server redémarre. Il utilise ssh -G pour une résolution de configuration fiable et fonctionne sur un socket tmux isolé nommé mcp-ssh afin d'éviter toute interférence avec vos sessions personnelles. L'ensemble d'outils inclut des fonctions pour ouvrir des sessions, envoyer des commandes ou des frappes de touches brutes, capturer des instantanés d'écran et effectuer des transferts de fichiers distants via des outils de lecture et d'écriture dédiés.
Ce que vous pouvez faire avec
- 1Surveiller des processus distants de longue duréeUn agent IA peut vérifier l'avancement d'un build ou d'un téléchargement en arrière-plan sans interrompre la tâche.
- 2Effectuer des opérations de fichiers à distanceUn développeur peut ordonner à un agent de lire ou de modifier des fichiers de configuration sur un serveur distant.
- 3Inspecter manuellement l'activité de l'agentUn utilisateur humain peut s'attacher au socket tmux spécifique pour observer le travail du terminal de l'agent en temps réel.
- 4Gérer les entrées de terminal interactivesL'agent peut envoyer des combinaisons de touches spécifiques comme Ctrl+C pour gérer les processus en cours.
Extrait du README du projet. Chaque cas d'utilisation est vérifié par rapport à une citation du document.
Outils MCP ssh-tmux 9
Détectés depuis le 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
| Nom | Description | Type |
|---|---|---|
| FASTMCP_TRANSPORT | — |
Vérifications automatisées
Exécuté le 14 nov. 2026Rapport complet →Pas encore vérifié. Un serveur nécessite un score de 80, aucune faille sérieuse et suffisamment de données pour que nous puissions effectuer les vérifications. Fonctionnement des vérifications · Ce qu'il faut corriger pour gagner des points
- Dépôt source lié et accessibledevnullvoid/mcp-ssh-tmux is public and reachablegithub.com/devnullvoid/mcp-ssh-tmux ↗Réussi
- Le nom du package correspond au dépôt sourceNon vérifié
- Provenance du build (attestation Sigstore)Non vérifié
- Licence open source (OSI)MITspdx.org/licenses/MIT.html ↗Réussi
- Commit ou version publiée au cours de l'année écouléeLast commit or release 2026-10-03github.com/devnullvoid/mcp-ssh-tmux ↗Réussi
- OpenSSF ScorecardNon vérifié
- Nom du package non proche d'un package populaireNon vérifié
- Aucun avis critique dans le package ou ses dépendancesNon vérifié
- Aucune instruction cachée destinée au modèle9 tool descriptions and the README read; no override phrases, credential paths or hidden charactersRéussi
- Les outils destructifs sont étiquetésNo tool named like delete, drop or execRéussi
- Le point de terminaison distant répond à la poignée de main MCPNon vérifié
README
Voir sur 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
Questions sur ssh-tmux MCP
Quels outils ssh-tmux MCP fournit-il ?
Il expose 9 outils, dont open_session, send_command, send_keys, get_snapshot, read_remote_file.
Comment puis-je voir ce que l'agent fait en temps réel ?
Vous pouvez exécuter manuellement une commande tmux pour vous attacher au socket dédié et visualiser les sessions actives.
Les connexions SSH restent-elles actives si le serveur redémarre ?
Oui, les connexions sont persistantes car elles sont gérées au sein d'une instance tmux.