SSH MCP ServerVerifiedFeatured

An SSH MCP server — a multitool that saves you and your AI agent time and tokens on debugging, development and server maintenance

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.

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.

Config

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

Installation

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

npx -y @hypnosis/ssh-mcp-server

Add it to Claude Code 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",
      "port": 22,
      "privateKeyPath": "~/.ssh/your_private_key"
    }
  }
}

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

Codex CLI, opencode, Qwen Code, Gemini CLI and other clients take the same command and the same environment variable — see the repository README.

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.

Tools

18 SSH MCP tools for server operations. Every tool names a connection profile — there is no machine the server falls back to.

ssh_exec

Run one command or a whole batch on a remote machine. The destructive-command guard checks the command before it reaches SSH, and long work can be detached and followed as a background job.

ssh_file_read

Read one or several remote files in a single round trip, text or binary, with size caps that say when output was truncated instead of pretending it was complete.

ssh_file_write

Write files to a remote machine. Content lands next to the target under a temporary name and takes its place with one atomic rename; SHA-256 verification is optional and reports "verified", "mismatched" or "could not check" as three distinct outcomes.

ssh_file_list

List a remote directory with optional glob filtering and recursion, returning sizes, permissions and modification times as structured data.

ssh_upload

Upload a file or a whole directory over SSH. Binary-safe, atomic, with integrity checks — the way to move binaries, archives, keys and anything larger than a heredoc can carry.

ssh_download

Download a file or a whole directory over SSH, binary-safe and integrity-checked, into a local path you name.

ssh_job_status

Report the state of a detached background job — running, finished or lost — along with the last lines it has written, so every look says how far the work got.

ssh_job_output

Read accumulated output of a background job from a byte offset, so a long-running task can be followed without re-reading what you already have.

ssh_job_list

List background jobs on a machine and sweep away the finished ones past their TTL.

ssh_job_kill

Signal a background job's whole process group, so nothing it spawned is left running behind it.

ssh_log_tail

Read the last N lines of one or several logs, glob supported, including the log of a Docker container addressed by name.

ssh_log_search

Search logs by pattern across files or through a container's log, with context lines and caps that keep an AI agent's context window intact.

ssh_snapshot

One-shot health snapshot of a machine: services, resources, Docker, network and recent errors, batched into a single round trip.

ssh_monitor

Transport control for the SSH layer: connection stats, reload, test a machine before touching it, list the configured profiles, close a shared connection.

ssh_audit_baseline

Read-only server audit in one round trip: system, disk, memory, network, ssh configuration, services, Docker, firewall and pending updates, with findings already classified.

ssh_tls_check

Check a domain's certificate: expiry, SAN list, chain and whether a renewal hook is in place.

ssh_disk_breakdown

Answer where the disk went — du top-N by directory, Docker usage, journald, package and build caches.

ssh_service_status

systemctl status for one unit plus a journalctl tail, so a failed service explains itself in a single answer.

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

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.

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

A blocked command names what it would have stopped — the running container, the matching processes, the volume — instead of refusing in the abstract. An intentional destructive command passes with an explicit confirmation marker.

Documentation

• Tool reference: https://github.com/hypnosis/ssh-mcp-server/blob/main/docs/tools.md
• File transfer: https://github.com/hypnosis/ssh-mcp-server/blob/main/docs/transfer.md
• Server audits: https://github.com/hypnosis/ssh-mcp-server/blob/main/docs/audit.md
• Security and path restrictions: https://github.com/hypnosis/ssh-mcp-server/blob/main/docs/security.md

License

MIT