mcp-ssh-live
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-ssh-live tail the nginx access log on production"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-ssh-live
Interactive, streaming SSH tool for LLM agents via MCP (Model Context Protocol).
Lets LLM agents (Claude, Cursor, Zed) spawn long-running remote commands and watch their output arrive line-by-line in chat — instead of blocking for hours waiting for a ssh_exec to return.
┌─────────────┐ JSON-RPC/stdio ┌──────────────────┐ SSH ┌─────────────┐
│ Zed / │ ────────────────── │ mcp-ssh-live │ ───────────────── │ your remote │
│ Claude / │ │ (Python) │ │ server(s) │
│ Cursor │ │ │ │ │
└─────────────┘ └──────────────────┘ └─────────────┘
^ ^
| |
ring buffers SFTP + exec
+ reader threadsWhy this exists
Other SSH-MCP servers (tufantunc/ssh-mcp, classfang/ssh-mcp-server, AiondaDotCom/mcp-ssh, …) are all request/response: send a command, wait for it to finish, get the full output. Long jobs — parsers, builds, deploys, log tails — are unusable. The LLM either blocks past the MCP client's 60 s timeout, or falls back to nohup … & + tail -n 10 log polling that loses lines and has no kill-signal story.
mcp-ssh-live splits the one SSH primitive into spawn + tail + signal + stdin, so an agent can:
Start
python parser.pyon a remote box, get ajob_idin <100 ms.Poll
ssh_tail(job_id, since_line_no, wait_ms=5000)in a loop and stream output into the chat live.Send SIGTERM / SIGKILL / SIGINT via
ssh_signalwhen the user wants to stop.Feed
sudopasswords or REPL input viassh_send_stdin.Upload / download files via SFTP (
ssh_upload/ssh_download) — binary-safe, with sha256 on both sides.Manage jobs across multiple hosts simultaneously.
Related MCP server: lms-ssh-client-mcp
Features
10 MCP tools covering synchronous exec, streaming spawn+tail, signals, stdin, SFTP, host/job registry management.
OpenSSH-compatible signal delivery. Captures the remote PID at spawn time, falls back to
kill -SIG <pid>on a fresh exec channel when paramiko's in-channelsend_signalis ignored by the server (which is the common case).Ring-buffered output (default 10 000 lines per stream) with condition-variable-backed blocking
wait_mssossh_tailis near-live without busy-polling.Multi-host: one process manages several SSH targets; each tool call can pick a host by alias.
Auto-reconnect on transient network / sshd hiccups (configurable retries + delay).
Graceful shutdown: TERM → 5 s grace → KILL for every running remote process when the server exits.
Opt-in disk log mirror (
--log-dir) — every streamed line also written to<log_dir>/<job_id>.logso full output survives ring-buffer eviction and server restarts.Secrets never leak into MCP responses: passwords live in env vars, only variable names appear in
ssh_list_hosts.
Quick start
1. Install
pipx install mcp-ssh-liveOr, for a project-local editable install:
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e .Requires Python 3.10+.
2. Try it from the command line
# Start the MCP server — no SSH credentials needed at startup
mcp-ssh-liveThe server starts empty and waits for an MCP client to connect. Credentials are provided at runtime by the agent via ssh_connect (see step 4). If you prefer to pre-configure a host at startup, you can still pass --host, --user, --password-env flags — see Configuration.
3. Register with an MCP client
Zed
Edit ~/.config/zed/settings.json (or .zed/settings.json for per-project).
Windows (use the Python executable directly — Zed doesn't pick up PATH the same way as a terminal):
Find your Python path: open a terminal and run
where python.
{
"context_servers": {
"ssh-live": {
"enabled": true,
"command": "C:/path/to/python.exe",
"args": ["-m", "mcp_ssh_live"],
"env": {
"FASTMCP_DISABLE_VERSION_CHECK": "1",
"PYTHONUNBUFFERED": "1"
},
"settings": {}
}
},
"agent": {
"always_allow_tool_actions": true,
"always_allowed_tools": {
"ssh_connect": true, "ssh_disconnect": true,
"ssh_exec": true, "ssh_spawn": true, "ssh_tail": true,
"ssh_signal": true, "ssh_send_stdin": true,
"ssh_list_jobs": true, "ssh_remove_job": true,
"ssh_upload": true, "ssh_download": true, "ssh_list_hosts": true
}
}
}macOS / Linux (if installed via pipx — binary is in PATH):
{
"context_servers": {
"ssh-live": {
"source": "custom",
"enabled": true,
"command": "mcp-ssh-live",
"args": [],
"env": {
"FASTMCP_DISABLE_VERSION_CHECK": "1",
"PYTHONUNBUFFERED": "1"
}
}
},
"agent": {
"always_allow_tool_actions": true,
"always_allowed_tools": {
"ssh_connect": true, "ssh_disconnect": true,
"ssh_exec": true, "ssh_spawn": true, "ssh_tail": true,
"ssh_signal": true, "ssh_send_stdin": true,
"ssh_list_jobs": true, "ssh_remove_job": true,
"ssh_upload": true, "ssh_download": true, "ssh_list_hosts": true
}
}
}Save the file. No restart needed in most cases, but if the indicator stays red — close and reopen Zed.
3b. Enable in the Agent Panel
Open the Agent Panel (right sidebar).
Click
···(top-right of the panel) → Settings → MCP Servers.Find
ssh-liveand toggle it ON.The indicator next to
ssh-liveshould turn green within a few seconds.
If it stays red — check
Zed.log: Command Palette →zed: open logand look forssh-live. The most common fix: thecommandpath in settings is wrong. Runwhere python(Windows) orwhich python(macOS/Linux) to get the correct path.
There's a full config template at .zed/settings.json.example.
Claude Desktop
~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"ssh-live": {
"command": "mcp-ssh-live",
"args": [],
"env": { "FASTMCP_DISABLE_VERSION_CHECK": "1" }
}
}
}Cursor
~/.cursor/mcp.json — same shape as Claude Desktop.
4. Ask your agent
Once registered, just tell the agent your SSH details in chat. It calls ssh_connect(...) automatically — credentials never touch the config file.
Stream a live log:
Connect to 1.2.3.4 as root, password is
···. Runtail -f /var/log/syslogfor 30 seconds, then stop.
The agent picks ssh_spawn → loops ssh_tail(wait_ms=5000) → ssh_signal("TERM") → ssh_remove_job, streaming lines into the chat the whole time.
Upload a local file to the server:
Connect to 1.2.3.4 as root, password is
···. UploadC:/Users/me/builds/app-1.0.zipto/opt/app/releases/app-1.0.zipon the server.
The agent calls ssh_connect(...) then ssh_upload(local_path="C:/Users/me/builds/app-1.0.zip", remote_path="/opt/app/releases/app-1.0.zip") — binary-safe, atomic, with sha256 verification printed in the reply.
Key auth instead of password:
Connect to 1.2.3.4 as deploy using key
~/.ssh/id_ed25519. Upload./dist/bundle.jsto/var/www/html/bundle.js.
Multiple servers at once:
Connect to prod at 1.2.3.4 and stage at 10.0.0.5 (both as root, password
···). Deploy./release.tar.gzto/srv/app/on both.
Staged deploy — save credentials once, deploy step by step:
First, register both servers by alias so you don't repeat credentials every time:
Save SSH connection to 1.2.3.4 as
deploy_test— userdeploy, password···. Save SSH connection to 5.6.7.8 asdeploy_production— userdeploy, password···.
The agent calls ssh_connect(host="1.2.3.4", user="deploy", password="...", alias="deploy_test") and the same for deploy_production. Both aliases stay active for the rest of the session.
Then deploy to test first:
Upload everything from the local
./deploydirectory to/srv/app/ondeploy_test. Run/srv/app/healthcheck.shafterwards and show me the output.
The agent calls ssh_upload for each file in ./deploy, then ssh_exec(command="/srv/app/healthcheck.sh", host="deploy_test") and streams the result.
If the output looks good, deploy to production:
Looks good. Now upload the same
./deploydirectory to/srv/app/ondeploy_production.
The agent reuses the saved deploy_production alias — no need to re-enter credentials — and repeats the upload.
Tools
Tool | What it does |
| Add and open an SSH connection at runtime. Returns an |
| Close a connection and remove it from the registry. |
| Run a short command synchronously; returns full stdout/stderr/exit_status. Timeout triggers SIGTERM → SIGKILL. |
| Start a background job, return |
| Stream new lines incrementally. Blocks up to |
| Send TERM/KILL/INT/… via paramiko + |
| Write to a running job's stdin — sudo passwords, REPL input. |
| List every job the server knows about: id, cmd, label, status, exit_status, line counts. |
| Drop a job from the registry. Running jobs need |
| Run a command via |
| Check status and tail output of a persistent job. |
| SFTP upload, atomic |
| SFTP download, atomic |
| Enumerate configured hosts (alias, address, auth method, connected, active_jobs, is_default). Never leaks passwords. |
Full JSON schemas and examples: SPEC.md.
Configuration
Credential-free mode (recommended)
Start the server with no SSH arguments. The agent receives credentials from the user in chat and connects via ssh_connect:
mcp-ssh-liveNo credentials in any config file. The agent connects on demand:
> "Connect to 1.2.3.4 as root, password is …"
Agent → ssh_connect(host="1.2.3.4", user="root", password="…")
Agent → ssh_exec(command="hostname")Pre-configured hosts (optional)
If you prefer hosts to be available immediately without an ssh_connect call, pass them via CLI flags or a TOML file. Credentials go into env vars — never on the command line.
export SSH_PASSWORD='your-password'
mcp-ssh-live \
--host prod=1.2.3.4:22 \
--host stage=10.0.0.5 \
--user root \
--password-env SSH_PASSWORD \
--default-host prod \
--insecure-auto-add \
--log-dir ~/.cache/mcp-ssh-live/logs \
--log-level INFORun mcp-ssh-live --help for the full flag list.
TOML config file
~/.config/mcp-ssh-live/config.toml:
default_host = "prod"
[hosts.prod]
host = "1.2.3.4"
port = 22
user = "root"
password_env = "PROD_PASS"
[hosts.stage]
host = "10.0.0.5"
user = "deploy"
key = "~/.ssh/stage_key"
[limits]
ring_buffer_lines = 10000
max_jobs_per_host = 50
reap_finished_after_sec = 600
reconnect_retries = 3
reconnect_delay_sec = 2.0
[server]
insecure_auto_add = false
known_hosts = "~/.ssh/known_hosts"
log_dir = "~/.cache/mcp-ssh-live/logs"Full reference: docs/CONFIG.md.
Auth
Password:
--password-env SSH_PASSWORD— name of the env var. Never pass passwords on the command line (visible inps).Key:
--key ~/.ssh/id_ed25519. Optional passphrase via--key-passphrase-env NAME.Agent: omit both — paramiko will try the SSH agent and default key locations.
Common gotchas
"I ran python parser.py and see no output for minutes"
Python (and many other programs) block-buffer stdout when stdin is not a TTY. The output is fine — it's sitting in a buffer on the remote side. Three fixes, pick one:
# Option 1: pty=True
ssh_spawn(command="python parser.py", pty=True)
# Option 2: unbuffered Python
ssh_spawn(command="python -u parser.py")
# Option 3: env var
ssh_spawn(command="python parser.py", env={"PYTHONUNBUFFERED": "1"})For non-Python tools: stdbuf -oL <cmd> or unbuffer <cmd> (from expect).
"ssh_signal returns sent=True but the job keeps running"
OpenSSH's sshd typically ignores channel.send_signal (the RFC 4254 in-channel way). mcp-ssh-live falls back to kill -<SIG> <pid> on a fresh exec channel, using the PID captured from the PID=<n> wrapper at spawn time. The response tells you which path worked:
{"sent_via_channel": false, "sent_via_pid": true, ...}If both are false, the spawn wrapper couldn't capture a PID (extremely rare — only happens if capture_pid=False was forced or the remote shell is very non-standard).
"Host key verification failed"
By default mcp-ssh-live respects ~/.ssh/known_hosts and refuses unknown keys. For the first connection either:
SSH into the host once by hand so the key is trusted, or
Pass
--insecure-auto-add(INSECURE — vulnerable to MITM on first connect), orPoint at a custom file via
--known-hosts /path/to/file.
"Tool calls hang for 60 seconds then error out"
If you see csp request task for "initialize" took over 60s in Zed's log: FastMCP tries to fetch its latest version from PyPI on startup. On air-gapped networks or slow DNS, this can time out. Fix with the env var:
FASTMCP_DISABLE_VERSION_CHECK=1More in docs/TROUBLESHOOTING.md.
Security
Passwords pass through env vars only, never command-line arguments (which would show up in
ps).ssh_list_hostsnever returns the password itself — only the env var name and the key file path.Known-hosts is enforced by default.
Sandboxing is at the MCP client level: whichever client you use (Zed, Claude Desktop, Cursor) is the thing asking the user to approve each tool call. Once approved,
mcp-ssh-liveruns whatever the LLM supplied verbatim — there is no command-level sanitization. This is the whole point of the tool.The LLM gets a shell on your server. If that bothers you, use a dedicated restricted user, jailed with
ForceCommand/ rbash / containers.
Documentation
Quick start — install, register, run in 4 steps (this file).
SPEC.md— full technical specification, all tool contracts with JSON shapes.docs/CONFIG.md— complete CLI + TOML reference.docs/USAGE.md— real-world examples per tool.docs/TROUBLESHOOTING.md— common failure modes with fixes.docs/DEVELOPMENT.md— how to hack on the server itself.CHANGELOG.md— release history.
Project status
v0.1.0 — phases 1-5 complete.
Phase | Feature | Status |
1 | Skeleton + | ✅ |
2 | Jobs + streaming tail | ✅ |
3 | Signals + stdin | ✅ |
4 | SFTP + multi-host | ✅ |
5 | Auto-reconnect + graceful shutdown + disk log mirror | ✅ |
6 | Docs + CI + PyPI publish | in progress |
68 unit tests. Acceptance-tested end-to-end against a real Ubuntu 24.04 sshd: streaming, signals, SFTP round-trip, disk mirror, multi-host.
Contributing
Design feedback on SPEC.md and docs/DEVELOPMENT.md is always welcome. Before opening a code PR:
pip install -e ".[dev]"pytest— all 68 tests must pass.ruff check .andblack --check .for style.If the change touches a tool schema, update
SPEC.mdfirst and explain why in the PR.
License
MIT. See LICENSE.
Related projects
Reviewed before building this; all of them are request/response only, which is why this project exists:
Project | Stars | Language | Streaming? |
392 | TS | ❌ | |
332 | TS | ❌ | |
159 | JS | ❌ | |
63 | JS | ❌ |
Available Tools
14 toolsssh_connectA
Add a new SSH host at runtime and open the connection. Call this first before using ssh_exec / ssh_spawn / ssh_upload / ssh_download on a new server.
Returns an alias (e.g. 'h-3f8a1b2c') that you pass as the 'host' argument to all other tools. If you supply your own alias it will be used instead.
Auth: provide exactly one of password or key_path. If neither is given, paramiko tries the SSH agent and default key files (~/.ssh/id_*).
Calling ssh_connect again with the same alias updates the credentials and reconnects.
Inputs: host (required), user, password, key_path, +3 more. Returns: object
ssh_disconnectA
Close the SSH connection to a host and remove it from the registry. Any running jobs on that host are terminated (their channels are closed). After this call the alias is no longer valid for other tools.
Returns removed=false (not an error) if the alias wasn't registered — useful for idempotent cleanup.
Inputs: alias (required). Returns: object
ssh_downloadA
Download a file from the remote host to a local path via SFTP. Binary-safe.
Writes to <local_path>.partial first, then atomically replaces the final path on success. A failed or cancelled download never leaves a truncated file where downstream tooling would pick it up.
Size cap: max_bytes (default 100 MiB, hard ceiling 1 GiB). Remote size is checked via sftp.stat BEFORE the transfer starts; files that exceed the cap fail fast. Caps are enforced streaming-side too, so a misreported remote size can't trick us into filling the local disk.
Inputs: remote_path (required), local_path (required), host, max_bytes. Returns: object
ssh_execA
Run a shell command on the remote host and return its full stdout/stderr/exit status. Blocks until the command finishes or the wall-clock timeout expires (SIGTERM then SIGKILL).
WHEN TO USE ssh_exec:
Short commands that finish in under ~60s.
Fire-and-forget background tasks that must SURVIVE a disconnect (use nohup or screen so the process keeps running even if the MCP server restarts or Zed closes).
SURVIVING DISCONNECT — nohup pattern: ssh_exec('nohup python -u train.py > /tmp/train.log 2>&1 &')
process keeps running after disconnect; check later with:
ssh_exec('tail -n 50 /tmp/train.log') ssh_exec('ps aux | grep train.py')
SURVIVING DISCONNECT — screen pattern: ssh_exec('screen -dmS myjob bash -c "python train.py > /tmp/out.log 2>&1"')
reattach later: screen -r myjob
WARNING: ssh_spawn ties the remote process to the MCP channel — it dies on disconnect. Use ssh_exec+nohup/screen for tasks that must outlive the current session.
For real-time streaming output of a command you will watch to completion without disconnecting, use ssh_spawn + ssh_tail instead.
Inputs: command (required), host, timeout_ms, cwd, +1 more. Returns: object
ssh_list_hostsA
List every SSH host this mcp-ssh-live server knows about, along with its runtime state (connected, active_jobs). Use this to discover available target aliases in a multi-host setup, to confirm that a --host flag or TOML entry landed as expected, and to check the per-host active-jobs count before spawning another job.
The response NEVER includes secrets — only the names of password environment variables and the paths of key files. The actual password / key contents are resolved only at SSH handshake time, not here.
Each entry has: alias, host, port, user, auth ('password_env' | 'key' | 'agent'), password_env (str or null), key (str or null), key_passphrase_env (str or null), connected (bool; whether we currently hold a live SSH transport), active_jobs (int; jobs registered on this host that are still running), is_default (bool).
Inputs: no named parameters. Returns: object
ssh_list_jobsA
List every job registered on this mcp-ssh-live server — running, finished-but-not-yet-reaped, and crashed. Returns metadata only (job_id, cmd, host, label, started_at, finished_at, exit_status, status, pid, pty, stdout_lines, stderr_lines); use ssh_tail to fetch the actual output of a specific job.
Filter by host with the 'host' argument (alias or raw address). Pass include_finished=false to see only still-running jobs, which is typical when deciding whether to spawn a new one without hitting the max_jobs_per_host cap.
Finished jobs are kept in the registry for a grace window (reap_finished_after_sec, default 600 s) so you can still fetch their final tail output after they exit.
Inputs: host, include_finished. Returns: object
ssh_persistent_statusA
Check the status of a persistent job started by ssh_run_persistent. Returns whether the process is still running, the last lines of its stdout and stderr logs, and the exit code (if it finished).
You need the PID and the log paths returned by ssh_run_persistent. Example: ssh_persistent_status(pid=12345, out_log='/tmp/mcp-persistent/abc123/out.log', err_log='/tmp/mcp-persistent/abc123/err.log')
Inputs: pid (required), out_log (required), err_log (required), host, +1 more. Returns: object
ssh_remove_jobA
Drop a job from the registry, freeing its slot against max_jobs_per_host and releasing its ring buffers.
Finished / crashed / killed jobs can always be removed. STILL-RUNNING jobs require force=True, which closes the SSH channel (sends EOF to the remote's stdin) but does NOT guarantee the remote process dies — for a hard kill call ssh_signal(KILL) FIRST and then ssh_remove_job.
Returns removed=True if a job was actually dropped, removed=False if the id wasn't present (a no-op, not an error — useful for idempotent cleanup scripts that don't know whether a job is still around).
Inputs: job_id (required), force. Returns: object
ssh_run_persistentA
Run a command on the remote host that SURVIVES MCP disconnect, Zed restart, or any interruption to the current session. The process runs via nohup in the background; its stdout and stderr are saved to log files on the remote server.
Returns immediately with the remote PID and log file paths. Check progress later with ssh_persistent_status or manually: ssh_exec('tail -n 50 /tmp/mcp-persistent//out.log') ssh_exec('ps -p -o pid,stat,etime,cmd --no-headers || echo DEAD')
WHEN TO USE THIS (not ssh_spawn):
Multi-hour or overnight tasks (training runs, large parsers, database migrations, long builds).
Any task where losing the MCP connection would be catastrophic.
Tasks you want to start now and check on later.
WHEN TO USE ssh_spawn INSTEAD:
You need real-time streaming output in chat.
The task takes under ~10 minutes and you will stay connected.
NOTE: logs are NOT auto-deleted. Clean up manually with: ssh_exec('rm -rf /tmp/mcp-persistent/')
Inputs: command (required), host, label, work_dir, +2 more. Returns: object
ssh_send_stdinA
Write bytes to the stdin of a running job (one spawned by ssh_spawn). Used for password prompts (sudo -S -p ''), REPL input (python, node), and any interactive CLI that expects keystrokes.
By default a trailing '\n' is appended so the remote program sees a complete line (this is what 'sudo -S' and most line-based REPLs need). Set newline=False to send raw bytes without the terminator — useful for control characters (e.g. data='\x03' to send ^C to a pty-mode job, or data='\x04' for ^D / EOF).
Set close_stdin=True to close the remote's stdin AFTER the write, which signals EOF to programs like 'cat', 'wc', 'sort'. Leaving it open (default) lets you make more writes to the same job.
IMPORTANT: for password input, pair this with ssh_spawn(pty=True) AND the command 'sudo -S -p ""'. Without pty=True, sudo refuses to read the password from a pipe on most distros. Without the -p "" flag, sudo writes its prompt to stdout, which mixes into ssh_tail output.
Payload size is capped at 64 KiB per call. For larger input use ssh_upload to place a file on disk, then have the command read from it.
Inputs: job_id (required), data (required), newline, close_stdin. Returns: object
ssh_signalA
Deliver a POSIX signal (TERM, KILL, INT, HUP, QUIT, USR1, USR2, STOP, CONT, and a few others) to a job started by ssh_spawn. Use TERM (polite, the default) for graceful shutdown; use KILL only when TERM fails to stop the job within a reasonable window.
Delivery strategy: we first try paramiko's in-channel send_signal (often ignored by OpenSSH sshd), then fall back to 'kill - ' on a fresh SSH session using the PID captured at spawn time. Both paths are attempted unless use_pid_fallback=False.
Pass wait_ms > 0 to block up to that many milliseconds waiting for the job to actually exit; the response then includes the real exit_status. Otherwise we return immediately with still_running indicating whether the signal took effect within the fire-and-forget window.
Common patterns:
Polite stop, wait up to 5 s:
ssh_signal(job_id, 'TERM', wait_ms=5000)
Hard kill, don't wait (verify via ssh_tail later):
ssh_signal(job_id, 'KILL')
Interrupt (like Ctrl-C):
ssh_signal(job_id, 'INT')
Inputs: job_id (required), signal, wait_ms, use_channel, +1 more. Returns: object
ssh_spawnA
Start a shell command on the remote host IN THE BACKGROUND and return a short job_id immediately (<100 ms). Use ssh_tail to stream output line-by-line while the job runs.
WHEN TO USE ssh_spawn:
You need real-time output in chat (builds, deploys, log tails).
The command takes more than ~60s but you WILL stay connected.
WARNING — PROCESS DIES ON DISCONNECT: ssh_spawn ties the remote process to the MCP server's SSH channel. If the MCP server restarts, Zed closes, or the connection drops — the remote process receives SIGHUP and dies. Do NOT use ssh_spawn for tasks that must survive a disconnect (multi-hour training runs, overnight parsers, etc.).
FOR TASKS THAT MUST SURVIVE DISCONNECT — use ssh_exec with nohup or screen instead: ssh_exec('nohup python -u train.py > /tmp/train.log 2>&1 &') ssh_exec('screen -dmS myjob bash -c "python train.py"') Then check progress with: ssh_exec('tail -n 50 /tmp/train.log') ssh_exec('screen -r myjob')
BUFFERING GOTCHA: many programs block-buffer stdout when stdin is not a TTY, so you see nothing until exit. Fix: pass pty=True, or use 'python -u' / PYTHONUNBUFFERED=1 / 'stdbuf -oL'. pty=True merges stderr into stdout.
Inputs: command (required), host, cwd, env, +2 more. Returns: object
ssh_tailA
Stream incremental output from a job started by ssh_spawn. Given a monotonic cursor 'since_line_no', return every buffered line with line_no > cursor (up to max_lines). If wait_ms > 0 and nothing new is available, block up to wait_ms milliseconds for new output. Returns still_running=False and exit_status when the job has finished.
Canonical polling loop (use this): cursor = 0 while True: r = ssh_tail(job_id, since_line_no=cursor, wait_ms=5000, max_lines=500, stream='both') for ln in r['lines']: show_to_user(ln) cursor = r['last_line_no'] if not r['still_running']: break
If r['buffer_truncated'] is True, older output was evicted from the ring buffer before you read it — either live with the gap or increase limits.ring_buffer_lines on the server. This tool does NOT open a new SSH connection per call; all data comes from in-memory buffers maintained by the spawn's reader threads.
Inputs: job_id (required), since_line_no, wait_ms, max_lines, +1 more. Returns: object
ssh_uploadA
Upload a local file to the remote host via SFTP. Binary-safe; preserves arbitrary bytes unlike 'cat > file <<EOF' over ssh_exec.
Writes to <remote_path>.partial first, then renames atomically on success — a crashed upload never leaves a half-written file at the target path. Parent directories are auto-created (mkdir -p). If remote_path points at an existing directory, the local filename is appended (same as scp).
Size cap: max_bytes (default 100 MiB, hard ceiling 1 GiB). Returns a sha256 of the bytes actually transferred so the caller can verify integrity.
Optional mode (octal, e.g. 493 for 0o755) runs chmod on the remote after the transfer. A chmod failure is non-fatal — the bytes are already there; mode_set=null in the response means the chmod was skipped or rejected.
Inputs: local_path (required), remote_path (required), host, mode, +1 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Every tool has a clearly distinct purpose: connect/disconnect manage sessions, list hosts/jobs provide introspection, exec/spawn/persistent cover execution modes, upload/download handle file transfer, and tail/signal/send_stdin/remove_job/status manage spawned jobs. No two tools could be confused.
All tools follow a consistent snake_case pattern with the 'ssh_' prefix and a verb_noun structure (e.g., ssh_connect, ssh_download, ssh_list_hosts). There are no deviations or mixed conventions.
14 tools cover the full lifecycle of SSH operations—connection, command execution (synchronous, async with streaming, persistent), file transfer, job monitoring, and signaling—without being excessive. Each tool serves a distinct and necessary purpose.
The tool set provides a comprehensive surface for remote host management: connection management, multiple execution modes (blocking, streaming, persistent), file upload/download, stdin interaction, signaling, and comprehensive job tracking. There are no obvious gaps for the intended purpose of an SSH live server.
Maintenance
Related MCP Connectors
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Scoped, audited SSH exec, sessions, and SFTP on your saved servers without exposing credentials
Remote shell and detached long-running jobs on your own machines — no SSH, open ports or VPN.
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Related MCP Servers
- FlicenseAqualityDmaintenanceProvides LLMs with safe, controllable, and stateful SSH access to shell environments, enabling remote command execution and file transfers with async support and security features.1517 npm44-
- FlicenseAqualityCmaintenanceEnables LLMs to securely SSH into remote servers, execute commands, and manage files via SFTP including listing, reading, writing, deleting, and renaming files.11-
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to have persistent, fully interactive SSH sessions into remote hosts, behaving like a local terminal.14 npm2MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to securely execute commands on remote hosts via SSH and SFTP, with persistent shells, file transfers, screenshots, and an audit log.5MIT