SSH MCP Server — Remote server tools for AI agents

<table> <tr> <td width="104" valign="middle" align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/hypnosis/ssh-mcp-server/main/assets/icon-dark-128.png"> <img src="https://raw.githubusercontent.com/hypnosis/ssh-mcp-server/main/assets/icon-128.png" width="72" alt="SSH MCP Server"> </picture> </td> <td valign="middle"> <p><strong>An SSH MCP server — a multitool that saves you and your AI agent time and tokens on debugging, development and server maintenance.</strong></p> <p>Run commands, move files, read logs and audit machines over SSH — a cloud VPS, a bare-metal box, or the BusyBox router sitting in your closet.</p> </td> </tr> </table>

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, Cline, 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

Or write it by hand — the same server in the config shape most clients share:

{
  "mcpServers": {
    "ssh": {
      "command": "npx",
      "args": ["-y", "@hypnosis/ssh-mcp-server"],
      "env": {
        "SSH_PROFILES_FILE": "~/.claude/ssh-profiles.json"
      }
    }
  }
}

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.

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:

| Your machine | What you get | |---|---| | A router or NAS too small for modern file transfer | The file still lands — the old protocol is used automatically | | A server from ten years ago | The workflow still works; it just opens a fresh connection per command instead of reusing one | | A stripped-down image with no way to hash a file | The upload says "could not verify" instead of claiming a match nobody checked | | A box where a tool simply is not installed | The answer says "not measured" — never a zero that reads as "nothing there" |

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

| Raw SSH | Structured MCP | Your gain | |---|---|---| | Several commands and ASCII tables | Named fields in one result | One call, named fields and fewer round trips | | A missing tool can look like empty output | unavailable names what was not measured | Less guessing and fewer bad fixes | | You sort through disks, services and errors | The problem signals are already surfaced | Faster debugging |

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]