ssh-tmux MCP server
2026년 10월 3일 커밋tmux를 통해 지속적인 SSH 세션을 관리하여 AI agent가 시각적 스냅샷으로 원격 터미널과 상호작용할 수 있도록 합니다.
다른 이름 devnullvoid/mcp-ssh-tmux
- 스타
- 7
- Tools
- 9
- 다운로드, 30일
- —
- 최신 버전
- —
- 마지막 커밋
- 2026년 10월 3일
- 라이선스
- MIT
ssh-tmux MCP란?
ssh-tmux은(는) MCP server입니다. tmux를 통해 지속적인 SSH 세션을 관리하여 AI agent가 시각적 스냅샷으로 원격 터미널과 상호작용할 수 있도록 합니다. 9개 도구를 제공합니다. 예: open_session, send_command, send_keys.
프로젝트 README에서 생성된 요약
ssh-tmux MCP server 정보
이 MCP server는 AI agent를 사용하는 개발자가 시각적 스냅샷을 통해 지속적인 원격 터미널 세션을 관리할 수 있게 해줍니다. 로컬 tmux 인스턴스를 터미널 멀티플렉서로 활용하여, agent가 마치 화면을 보고 있는 사람처럼 원격 머신과 상호작용할 수 있도록 지원합니다. 이 방식은 agent가 터미널 출력에서 프롬프트와 에러를 직접 해석하므로, 명령 완료를 감지하기 위한 복잡한 정규식 패턴이 필요하지 않습니다.
사용자는 uv 또는 pip를 통해 로컬에 설치하고 Claude Desktop 또는 Cursor와 같은 클라이언트에 연결할 수 있습니다. 서버는 전용 tmux window에서 SSH 연결을 유지하므로, 클라이언트나 MCP server가 재시작되어도 세션이 그대로 유지됩니다. 신뢰할 수 있는 설정 해결을 위해 ssh -G를 사용하며, 개인 세션과 충돌을 피하기 위해 mcp-ssh라는 이름의 격리된 tmux socket에서 작동합니다. 이 도구 세트에는 세션 열기, 명령 또는 raw keystroke 전송, 화면 스냅샷 캡처, 전용 읽기 및 쓰기 도구를 통한 원격 파일 전송 기능이 포함되어 있습니다.
활용 사례
- 1장시간 실행되는 원격 프로세스 모니터링AI agent가 작업을 중단하지 않고 백그라운드 빌드나 다운로드 진행 상황을 확인할 수 있습니다.
- 2원격 파일 작업 수행개발자가 agent에게 원격 서버의 설정 파일을 읽거나 수정하도록 지시할 수 있습니다.
- 3agent 활동 수동 검사사용자가 특정 tmux socket에 연결하여 agent의 터미널 작업을 실시간으로 관찰할 수 있습니다.
- 4대화형 터미널 입력 처리agent가 실행 중인 프로세스를 관리하기 위해 Ctrl+C와 같은 특정 keystroke를 보낼 수 있습니다.
프로젝트의 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.
agent가 수행 중인 작업을 실시간으로 어떻게 확인할 수 있나요?
전용 소켓에 연결하는 tmux 명령어를 수동으로 실행하여 활성 세션을 확인할 수 있습니다.
서버가 재시작되어도 SSH 연결이 유지되나요?
네, tmux 인스턴스 내에서 관리되므로 연결이 지속됩니다.