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.

[![npm version](https://img.shields.io/npm/v/@hypnosis/ssh-mcp-server?style=flat-square&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/@hypnosis/ssh-mcp-server)
[![npm downloads](https://img.shields.io/npm/dm/@hypnosis/ssh-mcp-server?style=flat-square&logo=npm&logoColor=white&color=CB3837&label=downloads)](https://www.npmjs.com/package/@hypnosis/ssh-mcp-server)
[![tests](https://img.shields.io/github/actions/workflow/status/hypnosis/ssh-mcp-server/test.yml?branch=main&style=flat-square&logo=githubactions&logoColor=white&label=tests)](https://github.com/hypnosis/ssh-mcp-server/actions/workflows/test.yml)
[![Node.js](https://img.shields.io/node/v/@hypnosis/ssh-mcp-server?style=flat-square&logo=nodedotjs&logoColor=white&color=5FA04E)](https://nodejs.org/)
[![TypeScript](https://img.shields.io/npm/dependency-version/@hypnosis/ssh-mcp-server/dev/typescript?style=flat-square&logo=typescript&logoColor=white&color=3178C6&label=typescript)](https://www.typescriptlang.org/)
[![MCP SDK](https://img.shields.io/npm/dependency-version/@hypnosis/ssh-mcp-server/@modelcontextprotocol/sdk?style=flat-square&logo=modelcontextprotocol&logoColor=white&color=0F172A&label=MCP%20SDK)](https://modelcontextprotocol.io/)
[![License](https://img.shields.io/npm/l/@hypnosis/ssh-mcp-server?style=flat-square&color=2563EB)](LICENSE)

**[Install](#installation) · [Quick start](#quick-start) · [Tools](#tools) · [Security](#security) · [Docs](docs/) · [Contributing](CONTRIBUTING.md) · [Changelog](CHANGELOG.md)**

---

## 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:

| From version | What it unlocks | Below it |
|---|---|---|
| 5.6 | Shared multiplexed connection (`ControlPersist`) | Every command opens its own connection |
| 8.4 | Password and passphrase profiles (`SSH_ASKPASS_REQUIRE`) | Refused — but only for profiles that need a password; key-based profiles are unaffected |
| 9.0 | `scp` rides the SFTP protocol | Falls back to the classic scp protocol |

**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:

```bash
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:

```bash
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:

```json
{
  "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](docs/security.md#path-security).

### 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:

```json
{
  "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](secrets.json.example):

```json
{
  "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](docs/security.md#credentials-keep-the-secret-out-of-the-profiles-file).

### 2. Point your MCP client at it

**Claude Code** — one command, `-s user` makes the server available in every project:

```bash
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:

```json
{
  "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:

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

Or wri