Skip to main content
Glama
mcp-ssh-live

mcp-ssh-live

by pmboxbiz

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 threads

Why 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.py on a remote box, get a job_id in <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_signal when the user wants to stop.

  • Feed sudo passwords or REPL input via ssh_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-channel send_signal is ignored by the server (which is the common case).

  • Ring-buffered output (default 10 000 lines per stream) with condition-variable-backed blocking wait_ms so ssh_tail is 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>.log so 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-live

Or, 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-live

The 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

  1. Open the Agent Panel (right sidebar).

  2. Click ··· (top-right of the panel) → Settings → MCP Servers.

  3. Find ssh-live and toggle it ON.

  4. The indicator next to ssh-live should turn green within a few seconds.

If it stays red — check Zed.log: Command Palette → zed: open log and look for ssh-live. The most common fix: the command path in settings is wrong. Run where python (Windows) or which 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 ···. Run tail -f /var/log/syslog for 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 ···. Upload C:/Users/me/builds/app-1.0.zip to /opt/app/releases/app-1.0.zip on 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.js to /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.gz to /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 — user deploy, password ···. Save SSH connection to 5.6.7.8 as deploy_production — user deploy, 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 ./deploy directory to /srv/app/ on deploy_test. Run /srv/app/healthcheck.sh afterwards 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 ./deploy directory to /srv/app/ on deploy_production.

The agent reuses the saved deploy_production alias — no need to re-enter credentials — and repeats the upload.


Tools

Tool

What it does

ssh_connect(host, user?, password?, key_path?, port?, alias?, insecure_auto_add?)

Add and open an SSH connection at runtime. Returns an alias used by all other tools. Credentials never go into config files.

ssh_disconnect(alias)

Close a connection and remove it from the registry.

ssh_exec(command, host?, timeout_ms?, cwd?, env?)

Run a short command synchronously; returns full stdout/stderr/exit_status. Timeout triggers SIGTERM → SIGKILL.

ssh_spawn(command, host?, pty?, label?, cwd?, env?)

Start a background job, return job_id in <100 ms.

ssh_tail(job_id, since_line_no, wait_ms, max_lines, stream)

Stream new lines incrementally. Blocks up to wait_ms for new output. Returns still_running, exit_status, buffer_truncated.

ssh_signal(job_id, signal, wait_ms?)

Send TERM/KILL/INT/… via paramiko + kill -SIG <pid> fallback. Optionally waits for exit.

ssh_send_stdin(job_id, data, newline?, close_stdin?)

Write to a running job's stdin — sudo passwords, REPL input.

ssh_list_jobs(host?, include_finished?)

List every job the server knows about: id, cmd, label, status, exit_status, line counts.

ssh_remove_job(job_id, force?)

Drop a job from the registry. Running jobs need force=True (use ssh_signal first for a clean kill).

ssh_run_persistent(command, host?, cwd?, env?, label?, work_dir?)

Run a command via nohup — survives MCP disconnect. Returns PID + log paths.

ssh_persistent_status(pid, out_log, err_log, host?, tail_lines?)

Check status and tail output of a persistent job.

ssh_upload(local_path, remote_path, host?, mode?, max_bytes?)

SFTP upload, atomic .partial + rename, auto-mkdir parents, scp-style dir target, sha256 on both sides.

ssh_download(remote_path, local_path, host?, max_bytes?)

SFTP download, atomic .partial + rename, size cap enforced pre- and during-transfer.

ssh_list_hosts()

Enumerate configured hosts (alias, address, auth method, connected, active_jobs, is_default). Never leaks passwords.

Full JSON schemas and examples: SPEC.md.


Configuration

Start the server with no SSH arguments. The agent receives credentials from the user in chat and connects via ssh_connect:

mcp-ssh-live

No 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 INFO

Run 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 in ps).

  • 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), or

  • Point 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=1

More in docs/TROUBLESHOOTING.md.


Security

  • Passwords pass through env vars only, never command-line arguments (which would show up in ps).

  • ssh_list_hosts never 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-live runs 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


Project status

v0.1.0 — phases 1-5 complete.

Phase

Feature

Status

1

Skeleton + ssh_exec

✅

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:

  1. pip install -e ".[dev]"

  2. pytest — all 68 tests must pass.

  3. ruff check . and black --check . for style.

  4. If the change touches a tool schema, update SPEC.md first and explain why in the PR.


License

MIT. See LICENSE.


Reviewed before building this; all of them are request/response only, which is why this project exists:

Project

Stars

Language

Streaming?

tufantunc/ssh-mcp

392

TS

❌

classfang/ssh-mcp-server

332

TS

❌

bvisible/mcp-ssh-manager

159

JS

❌

AiondaDotCom/mcp-ssh

63

JS

❌


Available Tools

14 tools
ssh_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

    A4.7/5.0

    Scored across 14 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      D
      maintenance
      Provides LLMs with safe, controllable, and stateful SSH access to shell environments, enabling remote command execution and file transfers with async support and security features.
      15
      17 npm
      44
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to have persistent, fully interactive SSH sessions into remote hosts, behaving like a local terminal.
      14 npm
      2
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to securely execute commands on remote hosts via SSH and SFTP, with persistent shells, file transfers, screenshots, and an audit log.
      5
      MIT