Ssh MCP Server

SSH MCP Server

An MCP server that lets an AI coding agent — Claude Code, Codex, Gemini CLI, Hermes, or anything else that speaks MCP — run commands, move files, and audit live servers over SSH, using the OpenSSH client, keys, and config already on your machine.

Install · Quick start · Tools · Security · Docs · Contributing · Changelog

---

What it's for

You already ask an assistant about your servers. Without this, it hands you a command to paste, waits for you to paste the output back, and repeats — you become the transport. With it, the assistant reaches the machine itself and gets structured answers back.

The everyday jobs it was built for:

• Find out why something broke. One ssh_snapshot call returns services, resources, docker, network and recent errors together, instead of a dozen commands typed one at a time.
• Audit a machine you inherited. Disks, listening ports, firewall, pending updates, certificate expiry — batched into one round trip, read-only, with the findings already sorted into critical, warning and fine.
• Work through logs. Tail or search several journals at once, with context lines and a cap that keeps the answer readable.
• Ship files. A file or a whole directory, binary-safe, verified by sha256, put in place by atomic rename — never a half-written file where the old one used to be.
• Start work that outlives the conversation. A migration or a backup keeps running after the call returns; job state lives on the remote disk, so it survives a restart of this server too.

Why not just give the assistant a shell? Because a shell has no brakes and no memory of what it just did. Here every destructive command is checked before it leaves your machine, every transfer says plainly whether it could verify itself, and a broken pipe is reported as "could not check" instead of being passed off as success.

Why this one

It uses the SSH you already have. 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. One shared multiplexed connection per destination means you authenticate once, not once per command.

It still talks to old servers. OpenSSH has moved on; the machines in the rack often have not. Three features have version floors, and missing one degrades a feature instead of refusing the connection — a client from 2010 is still served:

It refuses to destroy what cannot be brought back. Two independent checks run before anything reaches the server. The first reads the command text and stops whole-container destruction — wiping a disk, dropping a database, crontab -r, removing a Docker volume, halting the machine. The second catches a recursive delete aimed at the filesystem root, a home directory or a system tree, including when a symlink leads there. Neither is a policy you have to configure, and both step aside for an explicit confirmation marker: this guards against the slip, not against you.

It speaks current MCP. Built on @modelcontextprotocol/sdk 1.30, TypeScript throughout, 2100+ unit tests plus a live suite that runs against real containers rather than mocks.

Requirements

• Node.js 18+
• A system ssh client on PATH — nothing is bundled. Any OpenSSH will run; see the version table above for what each floor unlocks.

ssh_monitor({ action: "stats", profile: "production" }) reports the client version it found and whether multiplexing is active.

Installation

You do not have to install anything. Every example below launches the server with npx -y, which fetches the package on first use and keeps it in the npx cache — the -y answers the prompt npx would otherwise ask before downloading:

npx -y @hypnosis/ssh-mcp-server

Install it globally if you would rather pin a version, work offline, or avoid the extra second npx spends checking the registry:

npm install -g @hypnosis/ssh-mcp-server

Then use ssh-mcp-server as the command in the client config instead of npx.

Quick start

1. Create a profile file

Put it wherever you like. The examples below use ~/.claude/ssh-profiles.json for Claude Code and ~/.codex/ssh-profiles.json for Codex:

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

Every call names its profile. 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, staging

A profile the server cannot use for SSH — no host, no username, or mode: "local" — is skipped without complaint, and fields it does not recognise 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 neighbours keep working.

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

Keep passwords out of the profiles file

Prefer keys. Where a password — or an encrypted key — is unavoidable, the secret does not belong in the profiles file: that file gets copied, pasted into issues and committed by accident. Point at a secrets file instead, with secretsFile at the top level, per profile, or both:

{
  "secretsFile": "~/.config/ssh-mcp/secrets.json",
  "profiles": {
    "production": {
      "host": "server.example.com",
      "username": "admin"
    },
    "appliance": {
      "host": "10.0.0.2",
      "port": 2222,
      "username": "operator",
      "secretsFile": "./appliance-secret.json"
    }
  }
}

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

{
  "production": { "password": "..." },
  "staging": { "passphrase": "..." }
}

• chmod 600 is required. The server refuses to read a secrets file that anyone but you can read, the same way ssh refuses a private key — and says which file and what to run.
• A relative path is resolved from the profiles file, not from the working directory the client happened to start the server in.
• A profile whose secrets file is missing, malformed or too permissive is reported as broken instead of quietly logging in without a password.
• A profile named in secretsFile but absent from the file is fine — key-based profiles need no entry.
• password and passphrase written directly in a profile still work, so existing setups keep running, but the secrets file wins and a warning is logged.

The password never travels in argv — it reaches ssh through an askpass helper reading one environment variable, so ps does not show it — and it is masked in the logs. Details in docs/security.md.

2. Point your MCP client at it

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

Or write it into ~/.claude.json by hand:

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

Codex CLI — same shape, TOML instead of JSON:

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

Or write it into ~/.codex/config.toml by hand:

[mcp_servers.ssh]
command = "npx"
args = ["-y", "@hypnosis/ssh-mcp-server"]

[mcp_servers.ssh.env]
SSH_PROFILES_FILE = "~/.codex/ssh-profiles.json"

Any other MCP client works too — it needs a command to run and one environment variable.

3. Restart the client

Done — the assistant can now reach your servers. Ask it to run ssh_monitor({ action: "list" }) to see the profile names it loaded, then ssh_monitor({ action: "stats", profile: "production" }): it reports the ssh client it found and whether multiplexing is active.

Tools

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

Commands and files

Long-running work — a command that outlives the call

Job state lives on the remote disk, not in this server's memory — jobs survive a restart of the MCP server itself.

Logs and health

Transfer — binary-safe, atomic, sha256-verified. Details in docs/transfer.md.

For binaries and large files use ssh_upload / ssh_download — not base64 chunks through ssh_exec, and not a heredoc through ssh_file_write. Heredoc writes corrupt binaries and offer no integrity or atomicity guarantee.

Audit — read-only, batched into one round trip. Details in docs/audit.md.

Security

Two levels of caution, and the difference between them is whether the loss can be undone:

• A warning is returned for a destructive but recoverable command — dropping a table, chmod 777, force-removing a container. You see it and decide.
• A refusal stops the call before it reaches the server when the loss would be final: destroying the whole container of the data, or reading something that the same command already destroyed.

Both are bypassed by an explicit # CONFIRMED-DESTRUCTIVE marker, so nothing is permanently forbidden — the guard is there to catch the slip.

What it deliberately does not see: a delete and a read split across two separate calls (no state is carried between invocations), and sinks of tools it does not special-case. It is a seatbelt, not a policy engine — the reasoning is written down in docs/decisions/007-refusal-threshold.md (Russian).

Path handling, quoting rules and per-profile path restrictions: docs/security.md.

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.

Documentation

Development

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.

Contributing

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

License

MIT — see LICENSE.