SSH MCP Server — Remote server tools for AI agents

It uses the OpenSSH client already on your machine: your keys, your ~/.ssh/config, your jump hosts, your agent forwarding. Nothing bundled, nothing to compile, no native bindings.

Works with Claude Code, Codex CLI, opencode, Gemini CLI, Qwen Code, Hermes and other MCP clients.

Install · Tools · Setup · Security · Roadmap · Docs · Changelog

Install in 30 seconds

No global installation required. npx downloads the package on first use:

npx -y @hypnosis/ssh-mcp-server

Add it to your MCP client — Claude Code, for example — for every project:

claude mcp add ssh -s user \
  -e SSH_PROFILES_FILE="$HOME/.claude/ssh-profiles.json" \
  -- npx -y @hypnosis/ssh-mcp-server

Then create ~/.claude/ssh-profiles.json with at least one machine:

{
  "profiles": {
    "production": {
      "host": "server.example.com",
      "username": "admin",
      "privateKeyPath": "~/.ssh/your_private_key"
    }
  }
}

That is enough to connect.

Codex, opencode, Qwen Code and other clients are covered in Set up the SSH MCP server.

Install as a plugin

Some clients — Claude Code, for example — can take the whole thing as a plugin instead:

/plugin marketplace add hypnosis/ssh-mcp-server
/plugin install ssh-mcp-server@ssh-mcp-server

The plugin reads ~/.claude/ssh-profiles.json unless SSH_PROFILES_FILE says otherwise, so create that file first and the server comes up with your machines already loaded.

Requirements

Node.js 18+ and a system ssh client on PATH. On Windows, use a key-based profile; password and passphrase profiles are not currently available.

Prefer a pinned version, offline work, or one less registry check per launch: npm install -g @hypnosis/ssh-mcp-server, then use ssh-mcp-server as the command instead of npx.

Related MCP server: ssh-mcp-server

Who this is for

• DevOps and SREs who want faster audits, incident checks and routine server work.

• Vibe coders and indie builders who ship with an AI assistant and run what they build on their own servers.

• Sysadmins and platform engineers who want structured tools instead of an unrestricted raw shell.

• Developers and small teams running their own VPS without a dedicated operations team.

• Homelab, NAS and router owners whose useful hardware has outlived its modern protocols.

Why an SSH MCP server instead of a raw shell

Fewer tokens, lower AI costs

A raw shell gives an AI agent a firehose: repeated commands, ASCII tables and log dumps. It burns tokens turning that noise into a picture of the server — your money.

Faster server debugging

Purpose-built tools batch routine checks, cap noisy output and return the part that matters. The agent spends less time translating terminal output and gets to the fix sooner.

Less guesswork, fewer AI mistakes

Structured answers say what was found, what could not be measured and what was truncated. That leaves the agent less room to fill gaps with a hallucination — and gives you fewer bad fixes, calmer deploys and more reliable code.

SSH compatibility: modern servers, legacy gear and Windows

Use your existing OpenSSH setup

No bundled SSH implementation, no native bindings, no rebuild per platform. Commands ride the system ssh client, so your keys, your ~/.ssh/config, your jump hosts and your agent forwarding all keep working exactly as they do in a terminal. When supported, one shared multiplexed connection per destination means you authenticate once, not once per command.

SSH support for legacy servers, routers and NAS devices

Send a file to a router with a modern scp and you get this:

scp app.conf router:/etc/
# scp: subsystem request failed on channel 0

Nothing is broken — a current scp speaks the new protocol, and the router does not know it. In a terminal you now go read a forum thread and come back with an extra flag. Here you do nothing: the transfer is tried, the refusal is recognized, the old protocol is used instead, and that machine is remembered so the next file goes straight there.

Fallbacks for older SSH clients and missing tools

Old gear gets a fallback, not a dead end. When a modern feature is missing, the server takes the older road where it can:

Built for the Model Context Protocol

Built on the official MCP SDK, TypeScript throughout, 2500+ unit tests plus a live suite that runs against real containers rather than mocks.

Raw SSH vs an SSH MCP server: the same job, both ways

SSH server health check

Situation: A deploy just went out. The server feels slow, and you do not know whether disk, memory, services, containers or errors are to blame.

Question: “Is this box healthy?”

Raw SSH

$ uptime
 10:42:17 up 18 days,  3:21,  2 users,  load average: 0.42, 0.31, 0.28
$ df -hT
Filesystem     Type   Size  Used Avail Use% Mounted on
/dev/sda1      ext4    40G   35G  5.0G  87% /
overlay        overlay  40G   35G  5.0G  87% /var/lib/docker/overlay2/...
$ free -h
               total        used        free      shared  buff/cache   available
Mem:           7.7Gi       4.9Gi       612Mi       121Mi       2.2Gi       2.5Gi
$ systemctl --failed
  UNIT              LOAD   ACTIVE SUB    DESCRIPTION
● api-worker.service loaded failed failed API background worker
$ docker ps -a
CONTAINER ID   IMAGE          STATUS                     PORTS
8e14d0b41c2a   api:latest     Up 3 minutes               0.0.0.0:8080->8080/tcp
65b894af2430   worker:latest  Exited (1) 2 minutes ago
$ ss -tulpn
Netid  State   Local Address:Port   Process
tcp    LISTEN  0.0.0.0:22          users:(("sshd",pid=842,fd=3))
tcp    LISTEN  0.0.0.0:8080        users:(("docker-proxy",pid=1942,fd=4))
$ journalctl -p err --since -1h | tail -50
Aug 20 10:39:14 prod api-worker[22104]: database connection timed out
Aug 20 10:39:14 prod systemd[1]: api-worker.service: Failed with result 'exit-code'.

That is still an abridged result. A complete check needs more commands for CPU, service states, container counts and recent errors, each with its own output format. Worse, a box without ss can look like it has zero listeners when the port check never ran.

Structured MCP result

ssh_snapshot({ "profile": "production" })

{
  "disk_pct": 87,
  "mem_pct": 64,
  "cpu_pct": 12,
  "load": "0.42 0.31 0.28",
  "containers": 7,
  "ports": 14,
  "services_running": 3,
  "recent_errors": 21,
  "unavailable": []
}

What the agent gains

A full ssh_audit_baseline result can be longer than a handful of raw command outputs — about 1,077 tokens versus 765 in our lab measurement. The saving comes from the complete workflow, not from making one response shorter.

In a real troubleshooting session, purpose-built tools reduced 49 separate command calls to 4 MCP calls. Every additional call starts another model turn with the accumulated conversation. Prompt caching can reduce the cost of repeated input, but new commands and their output still consume context. Fewer round trips mean fewer tokens across the session, less repeated analysis and a faster path to the answer.

Need the whole picture rather than the pulse? ssh_audit_baseline batches system, disk, memory, ports, sshd, failed units, Docker, firewall and updates. Findings arrive as CRITICAL / WARNING / OK; unmeasured sections are named instead of silently reading as zero.

Linux server log search

Situation: The API is timing out, but the same message may be in nginx, syslog, journald or an application log you cannot read with your normal user.

Question: “Where did that error come from?”

Raw SSH

$ grep -i "timeout" /var/log/nginx/error.log
2026/08/20 10:38:54 [error] upstream timed out while reading response header
$ grep -i "timeout" /var/log/syslog
Aug 20 10:39:14 prod api-worker[22104]: database connection timed out
$ grep -i "timeout" /var/log/app/*.log 2>/dev/null
$ journalctl -u api --since "1 hour ago" | grep -i timeout
Aug 20 10:39:14 prod api[22104]: database connection timed out after 30000ms

The third command looks clean, but 2>/dev/null also hid a permission error. "Nothing matched" and "nothing was read" now look identical. A busy log can also return thousands of lines and push the rest of the incident out of the agent's context.

Structured MCP result

ssh_log_search({ "profile": "production",
                 "path": ["/var/log/nginx/error.log", "/var/log/syslog", "/var/log/app/*.log"],
                 "query": "timeout", "context": 2, "since": "1h" })

{
  "matches": 34,
  "lines": [
    { "file": "/var/log/nginx/error.log", "line": 4821,
      "text": "upstream timed out while reading response header", "context": false },
    { "file": "/var/log/nginx/error.log", "line": 4822,
      "text": "client closed connection", "context": true }
  ],
  "files_searched": 6,
  "files_unreadable": ["/var/log/app/private"],
  "files_skipped": 12,
  "files_undated": [],
  "limited": false,
  "truncated": false
}

What the agent gains

since uses the server's clock, namesOnly: true returns only matching paths, and ssh_log_tail reads the last N lines from several logs in one call.

Safe remote config edits

Situation: You need to replace an nginx config on a live server. A dropped connection, wrong mode or unchecked copy could leave the service with a broken file.

Question: “Can I replace this config without leaving a partial file?”

Raw SSH

$ sudo sh -c 'cat > /etc/nginx/conf.d/api.conf' <<'EOF'
server {
    listen 80;
    location / { proxy_pass http://127.0.0.1:8080; }
}
EOF
$ echo $?
0

Exit code zero says the shell finished. It does not prove which bytes landed, and > truncated the old file before the first byte of the new one arrived. If the connection drops mid-write, the service is left with a partial config.

Structured MCP result

ssh_file_write({ "profile": "production",
                 "files": [{ "path": "/etc/nginx/conf.d/api.conf",
                             "content": "server {\n    listen 80;\n    location / { proxy_pass http://127.0.0.1:8080; }\n}\n",
                             "mode": "644", "sudo": true, "verify": true }] })

{
  "files": [{ "path": "/etc/nginx/conf.d/api.conf", "written": true,
              "verified": "verified", "reason": null, "bytes": 79 }]
}

What the agent gains

verified has three honest outcomes: verified, unavailable when the server has no hash tool, and skipped when verification was not requested. For reads, ssh_file_read accepts a list of paths; ssh_file_list handles globs, recursion, sizes and modes.

Run batch SSH commands with sudo

Situation: A deploy is ready, but nginx syntax, service state and recent errors must all be checked before traffic moves. One failed check should not disappear inside a combined dump.

Question: “Did every preflight check pass?”

Raw SSH

$ ssh admin@server.example.com 'sudo nginx -t'
nginx: configuration file /etc/nginx/nginx.conf test is successful
$ ssh admin@server.example.com 'sudo systemctl is-active nginx'
active
$ ssh admin@server.example.com 'sudo tail -5 /var/log/nginx/error.log'
2026/08/20 10:38:54 [error] upstream timed out while reading response header

Three connections return three unrelated outputs. If the commands are joined with ;, the shell reports only the last exit code; if they are joined with &&, later checks disappear after the first failure.

Structured MCP result

ssh_exec({ "profile": "production",
           "command": ["nginx -t", "systemctl is-active nginx",
                       "tail -5 /var/log/nginx/error.log"],
           "sudo": true })

{
  "commands": [
    { "command": "nginx -t", "exit_code": 0, "truncated": false, "clipped_bytes": 0,
      "stdout": "", "stderr": "nginx: configuration file /etc/nginx/nginx.conf test is successful\n" },
    { "command": "systemctl is-active nginx", "exit_code": 0, "truncated": false,
      "clipped_bytes": 0, "stdout": "active\n", "stderr": "" },
    { "command": "tail -5 /var/log/nginx/error.log", "exit_code": 0, "truncated": false,
      "clipped_bytes": 0, "stdout": "2026/08/21 09:14:02 [error] upstream timed out\n", "stderr": "" }
  ],
  "job_id": null
}

What the agent gains

The destructive-command guard checks the complete list before the first command runs. If one entry is refused, every other entry is marked as not run and nothing is sent to the server.

Each command carries its own stdout and stderr. A command that ran and printed nothing has an empty string; a command that never ran has no such field at all, so the two cannot be confused. Output over 128 KB per command keeps both ends — the head for tables, the tail for logs — with a seam in between naming the amount, and clipped_bytes says how much was cut. Cutting happens on byte boundaries and steps back to the edge of a character, so a clipped answer never carries a replacement mark.

sudo reaches the server without a terminal: the profile's answer is handed to sudo on standard input. Which secret that is comes from sudoPassword when the profile names one and from password otherwise — a profile that logs in by key has no login password at all, and where a machine keeps the two apart the login one is the wrong answer. Where there is nothing to answer with, the reply says so and names the ways out, instead of leaving sudo's own advice about -S and askpass helpers. A command that reads its own standard input is never given the password, which would otherwise end up mixed into the data.

Run long-lived SSH jobs

Situation: A backup or migration will run longer than the agent session. The connection may close, but you still need its state, output and exit code later.

Question: “Will this job survive the conversation?”

Raw SSH

$ ssh admin@server.example.com 'pg_dump app | gzip > /srv/backups/app.sql.gz'
client_loop: send disconnect: Broken pipe

The terminal is gone. You now have to reconnect, find the process, inspect the target file and guess whether the backup finished or stopped halfway.

Structured MCP result

ssh_exec({ "profile": "production",
           "command": "pg_dump app | gzip > /srv/backups/app.sql.gz",
           "detach": true })

{
  "commands": [{
    "command": "pg_dump app | gzip > /srv/backups/app.sql.gz",
    "exit_code": null,
    "truncated": false,
    "timed_out": false,
    "blocked": false,
    "blocked_reason": null,
    "not_run": false,
    "warning": null
  }],
  "job_id": "mst0f2q1-9ab3c4d5"
}

What the agent gains

Job state lives on the remote disk, not in this server's memory. ssh_job_status distinguishes running, finished and lost; ssh_job_output continues from the last byte offset; and ssh_job_kill signals the whole process group instead of only its shell.

Transfer files to legacy routers and NAS devices

Situation: A current OpenSSH client tries SFTP, but the router or NAS only understands the classic scp protocol. The file must still arrive intact and replace its target safely.

Question: “Can this old device still receive a verified file?”

Raw SSH

$ scp app.conf operator@router:/etc/app.conf
subsystem request failed on channel 0
scp: Connection closed

The usual next step is to remember the legacy flag, retry the copy and then run a separate hash command—if the device has a hash tool at all.

Structured MCP result

ssh_upload({ "profile": "router", "local_path": "./app.conf",
             "remote_path": "/etc/app.conf", "sudo": true,
             "mode": "644", "owner": "root:root", "verify": true })

{
  "files": [{
    "path": "/etc/app.conf",
    "written": true,
    "verified": "verified",
    "reason": null,
    "bytes": 1284
  }]
}

What the agent gains

If the device has neither sha256sum nor openssl, the result says unavailable and names the reason instead of reporting a false match. Whole directories use recursive: true and verify their hashes in one batch.

Destructive command protection for AI agents

The guard runs locally, before a command reaches SSH. It separates operations that can be recovered from those that destroy the container holding the data, and it checks command order inside chains and batches.

Stop a destructive chain before it starts

A safe backup-and-replace sequence:

cp -r /srv/app /srv/app.bak && mv /srv/app /srv/app-old && rm -rf /srv/app

The same operations in the wrong order:

rm -rf /srv/app && cp -r /srv/app /srv/app.bak && mv /srv/app /srv/app-old
# REFUSED before the first command runs

The shell would delete the directory and only then discover that the backup source is gone. The guard sees that later steps read a target already destroyed by an earlier step, so the whole call stays on your machine. The same check catches dropdb app && pg_dump app > backup.sql.

Refuse irreversible loss, warn about recoverable changes

docker compose down -v is refused because -v removes named Docker volumes, including a database volume. Without -v, stopping the services is not treated as the same irreversible action.

Recursive deletion of the filesystem root, a home directory or system trees such as /etc, /var and /usr is also refused, including when a symlink leads there. An unresolved target such as rm -rf "$DIR"/* is refused too: "could not check" is not treated as "safe".

Confirm an intentional destructive command

Nothing is forbidden permanently. Add # CONFIRMED-DESTRUCTIVE to a reviewed command and it is allowed through. When the guard refuses one entry in a batch, the complete batch stops before execution, so the server is never left after a half-run operation.

The guard works within a single call. It cannot connect a delete in one invocation with a read in the next, or reason about tools it does not recognize. It is a seatbelt, not a policy engine: recoverable operations remain your call. Path restrictions and quoting rules are documented in docs/security.md.

SSH MCP tools for server operations

18 tools. Full parameters and examples live in docs/tools.md.

MCP tool safety annotations

Standard MCP annotations tell clients which tools are read-only, destructive, idempotent or open-world. See the full table.

Run SSH commands and manage remote files

Monitor long-running SSH jobs

Search logs and check server health

Upload and download files over SSH

Binary-safe transfers with integrity checks. Details in docs/transfer.md.

For binaries and large files use ssh_upload / ssh_download — base64 chunks and heredocs are not binary-safe or atomic.

Audit Linux servers over SSH

Read-only and batched into one round trip. Details in docs/audit.md.

Windows SSH compatibility mode

Windows uses compatibility mode automatically. When connection multiplexing is unavailable, the server switches to one connection per command. The same tools remain available over key-based SSH — no separate setup or Windows-specific implementation.

The destructive-command guard is covered in Destructive command protection for AI agents.

Set up the SSH MCP server

Run the package from Install in 30 seconds first, then create a profile file.

Create SSH connection profiles

Put it wherever you like — next to your agent's own config is the usual choice. The examples below use ~/.claude/ssh-profiles.json; for other agents swap the directory (~/.codex/, ~/.qwen/, ~/.config/opencode/):

{
  "profiles": {
    "production": {
      "host": "server.example.com",
      "username": "admin",
      "port": 22,
      "privateKeyPath": "~/.ssh/your_private_key"
    }
  }
}

Choose an SSH profile explicitly

There is no profile the server falls back to: each one is a different machine, and a command sent to the wrong machine is not something an error message can undo afterwards. Ask without a name and the answer lists the names to choose from:

ssh_exec({ command: "uptime" })
→ No profile specified. Name one explicitly: production

A profile the server cannot use for SSH — no host, no username, or mode: "local" — is skipped without complaint, and fields it does not recognize are left alone, so the file can be shared with other tools. A profile with a broken field is a different case: it is named along with the field and the value, and its healthy neighbors keep working.

Each profile optionally takes a pathSecurity block that whitelists or blacklists the paths file tools may touch — see docs/security.md.

A profile that logs in by key but needs sudo on the far side takes a sudoPassword — the secret sudo is answered with, which on many machines is not the login password. Keep it in the secrets file rather than here.

Keep SSH passwords and passphrases out of profiles

Prefer keys. If a password or encrypted-key passphrase is unavoidable, keep it in a separate secrets file, never in the profile itself:

{
  "secretsFile": "~/.config/ssh-mcp/secrets.json",
  "profiles": {
    "production": {
      "host": "server.example.com",
      "username": "admin"
    }
  }
}

The secrets file is keyed by profile name — see secrets.json.example:

{
  "production": { "password": "..." },
  "buildbox": { "sudoPassword": "..." }
}

sudoPassword is what sudo is answered with on that machine. A profile logging in by key has no login password to offer, and where the two differ the login one is the wrong answer; without it, password is used.

The secrets file must be readable only by you (chmod 600). Relative paths resolve from the profiles file; secrets stay out of argv and are masked in logs. See credentials security.

Configure Claude Code, Codex and other MCP clients

Choose the client you use and point it at the same profiles file.

Claude Code

One command; -s user makes the server available in every project:

claude mcp add ssh -s user \
  -e SSH_PROFILES_FILE="$HOME/.claude/ssh-profiles.json" \
  -- npx -y @hypnosis/ssh-mcp-server

Codex CLI

codex mcp add ssh \
  --env SSH_PROFILES_FILE="$HOME/.codex/ssh-profiles.json" \
  -- npx -y @hypnosis/ssh-mcp-server

opencode

Put it in ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "ssh": {
      "type": "local",
      "command": ["npx", "-y", "@hypnosis/ssh-mcp-server"],
      "enabled": true,
      "environment": {
        "SSH_PROFILES_FILE": "~/.config/opencode/ssh-profiles.json"
      }
    }
  }
}

Qwen Code

One command, same as the others:

qwen mcp add ssh \
  -e SSH_PROFILES_FILE="$HOME/.qwen/ssh-profiles.json" \
  npx -y @hypnosis/ssh-mcp-server

Other MCP clients

Gemini CLI, Hermes, Cline, an editor plugin or your own agent work the same way. All they need is a command to run and one environment variable.

Restart your MCP client

Restart the client, then run ssh_monitor({ action: "list" }) to confirm the profile loaded.

SSH MCP server configuration

The shared connection outlives this process on purpose: closing it on exit would cut the channel another window on the same machine is using.

SSH MCP server limitations

• Cancellation: closing SSH may leave the remote command running. Use detached jobs when control matters.

• Atomic writes: BSD and macOS cannot pre-check cross-filesystem renames.

SSH MCP server roadmap

• Full test run against macOS SSH hosts

• End-to-end compatibility run on Windows

• Multi-host audits — compare health across several SSH profiles in one call

• Import profiles from the existing ~/.ssh/config

• Resumable transfers for large files and unstable connections

• Remote operation timeline — commands, transfers and guard decisions in one audit trail

• Ready-made SSH troubleshooting playbooks

• Answers that reach the model — DONE: command output, matched log lines, machine names and snapshot sections travel in the fields, not only in the text

• Smaller MCP tool schemas — DONE: the tool list got 10% lighter, and a detached job now shows the last lines it wrote instead of being polled blind

• Long work under root — DONE: a detached job runs with sudo and is followed as root, and a key-only profile answers sudo with its own sudoPassword

Develop and test the SSH MCP server

npm install
npm run build           # tsc
npx tsc --noEmit        # types, plus dead declarations
npm run test:unit       # unit tests
npm run lab:up          # start the two test containers
npm run test:live       # live suite against those containers

The live suite runs against real containers — one BusyBox, one coreutils — because the two disagree quietly, and a mock agrees with whoever wrote it. See docs/architecture.md for the layout.

Like SSH MCP Server? ⭐

If you like the tool, give it a star on GitHub — it helps more people discover the project.

Contribute to the SSH MCP server

Issues and pull requests are welcome at github.com/hypnosis/ssh-mcp-server.

License

MIT — see LICENSE.