ssh-mcp

# SSH MCP Server v2

[![NPM Version](https://img.shields.io/npm/v/ssh-mcp)](https://www.npmjs.com/package/ssh-mcp)
[![Downloads](https://img.shields.io/npm/dm/ssh-mcp)](https://www.npmjs.com/package/ssh-mcp)
[![CI](https://github.com/tufantunc/ssh-mcp/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/tufantunc/ssh-mcp/actions/workflows/ci.yml)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/tufantunc/ssh-mcp/badge)](https://scorecard.dev/viewer/?uri=github.com/tufantunc/ssh-mcp)
[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/15082/badge)](https://www.bestpractices.dev/projects/15082)
[![codecov](https://codecov.io/gh/tufantunc/ssh-mcp/graph/badge.svg?branch=main)](https://codecov.io/gh/tufantunc/ssh-mcp)
[![License](https://img.shields.io/github/license/tufantunc/ssh-mcp)](./LICENSE)
[![GitHub issues](https://img.shields.io/github/issues/tufantunc/ssh-mcp)](https://github.com/tufantunc/ssh-mcp/issues)

**SSH MCP Server** is a security-first Model Context Protocol server that gives LLM agents controlled SSH access to remote hosts — with command classification, policy-based authorization, human-in-the-loop approval, and full audit logging.

> **The risk this server exists to manage.** Giving an LLM shell access on a remote host puts private data, untrusted input and network egress in one place — Simon Willison's ["lethal trifecta"](https://simonwillison.net/2025/Jun/16/the-lethal-trifecta/). Prompt injection has no general fix, so ssh-mcp assumes any command may be attacker-influenced: it classifies before executing, authorizes against a role × host-group matrix, gates destructive work behind approval, and records the decision either way. That narrows the blast radius; it does not remove the risk. Two things stay yours: **never point it at a root account**, and **never set `auto` approval on a production profile**. [SECURITY.md](./SECURITY.md) has the full threat model.

---

## Quick Start

### 1. Install

```bash
npm install -g ssh-mcp
```

### 2. Configure

Without a config the server still starts, so a client or directory can complete the MCP
handshake and read `tools/list` — but **every tool call is refused** until you configure it,
with a message naming the path below. Nothing runs on a host until this step is done.

Create the config file at the path for your platform:

| Platform | Path |
|---|---|
| Linux | `~/.config/ssh-mcp/config.toml` (or `$XDG_CONFIG_HOME/ssh-mcp/config.toml`) |
| macOS | `~/Library/Application Support/ssh-mcp/config.toml` |
| Windows | `%APPDATA%\ssh-mcp\config.toml` |

```toml
[defaults]
defaultProfile = "dev"
approvalMode = "ask-destructive"

[[profiles]]
name = "dev"
host = "192.168.1.100"
port = 22
user = "deploy"           # NOT root!
auth = "key"
keyRef = "~/.ssh/id_ed25519"
role = "admin"
approvalPolicy = "auto"    # dev is permissive
```

```bash
chmod 700 ~/.config/ssh-mcp && chmod 600 ~/.config/ssh-mcp/config.toml
```

The config decides which hosts, roles and policy rules this server honours, so it checks
that nobody but you can read it — and treats the two platforms differently, because the
question has a much clearer answer on one of them.

**Linux and macOS: enforced.** The mode check above, on the file *and* the directory —
which is why `chmod 700` is in that command, since `mkdir -p` under the default umask
leaves the directory 0755. The server refuses to start otherwise. "Only the owner" is
unambiguous here and `chmod` is a one-line fix.

**Windows: split by what the ACL actually allows.** There are no mode bits, so the ACL is
read instead — and read exposure and write exposure are not treated alike, because Windows
is much clearer about one of them than the other.

| The ACL lets another account… | Default |
|---|---|
| only **read** the config | reported, and the server starts |
| **change** the config | refused |
| nothing (no ACL at all) | refused — that is full control for everyone |
| …and if the ACL could not be read | refused, except when `icacls` is absent or the check timed out |

A config under `%APPDATA%` inherits access for you, `SYSTEM` and `Administrators` and needs
nothing done to it. One created elsewhere does not: a file under `C:\` inherits *read* for
every local account and *modify* for every authenticated one. The message names the two
`icacls` commands that fix it either way.

Read exposure is reported rather than refused because that is where Windows is genuinely
muddier than POSIX, and refusing over it blocked a config at the documented location
([#138](https://github.com/tufantunc/ssh-mcp/issues/138)). Write exposure is refused
because it is not muddy at all: another account being able to rewrite the file that decides
which hosts, roles and approval policy this server honours is an authorization bypass, not
a disclosure.

Two flags move the whole thing: `--strictConfigAcl` refuses everything the check objects
to, read-only grants included; `--allowUncheckedConfigAcl` reports everything and refuses
nothing. Neither combination leaves you without an exit, which is the lesson of #138.

### Exit statuses

| Status | Meaning |
|---|---|
| `0` | Clean shutdown |
| `1` | A defect in the server — printed with a stack trace; please report it |
| `2` | How it was invoked or configured — printed as a message, no stack |

A supervisor that treats any non-zero status as a failure needs no change. One
that matched on `1` to detect a startup problem should match on `2` as well.

Starting with nothing configured is **not** an exit-2 condition, as of the release that
added introspection without a config: the server starts so it can be described, and
refuses each tool call instead. A supervisor that used a non-zero exit to catch an
unconfigured deployment should watch for `starting unconfigured` on stderr, or read
`configured` from `GET /health` when running the HTTP transport.

### 3. Set credentials via environment variables

```bash
export SSH_MCP_PASSWORD="your-password"        # if using auth=password
# OR use SSH agent (recommended):
export SSH_AUTH_SOCK="$SSH_AUTH_SOCK"           # already set if agent running
```

### 4. Connect from your MCP client

**Claude Code:**
```bash
claude mcp add --transport stdio ssh-mcp -- ssh-mcp
```

**Claude Desktop / Cursor / Windsurf:**
```json
{
  "mcpServers": {
    "ssh-mcp": {
      "command": "ssh-mcp",
      "env": {
        "SSH_MCP_PASSWORD": "your-password"
      }
    }
  }
}
```

**Never pass passwords as CLI arguments** — they're visible via `ps aux`. Use env vars, config files, SSH agent, or OS keychain.

---

## Tools (14)

| Tool | Purpose | readOnly | destructive |
|------|---------|:--------:|:----------:|
| `list-connections` | Discover available hosts and connection status | ✅ | — |
| `list-sessions` | List active sessions per host | ✅ | — |
| `open-session` | Create a named interactive (stateful) or background session | — | — |
| `close-session` | Close a session. A background session's command is signalled (INT/TERM/KILL) before its channel is dropped | — | ✅ |
| `read-session-output` | Read output from background sessions (e.g., `tail -f`) | ✅ | — |
| `read-command` | Execute allowlisted read-only commands (`ls`, `cat`, `grep`, ...) | ✅ | — |
| `run-command` | Execute arbitrary commands (destructive/privileged need approval, unless `approvalPolicy = "auto"`) | — | — |
| `privileged-command` | Execute with sudo (needs approval, unless `approvalPolicy = "auto"`) | — | ✅ |
| `sftp-upload` | Upload a file via SFTP (replaces the destination unconditionally) | — | ✅ |
| `sftp-download` | Download a file via SFTP | ✅ | — |
| `sftp-list` | List a remote directory, bounded in entries and bytes | ✅ | — |
| `sftp-upload-file` | Stream a local file to the remote host, never through model context | — | ✅ |
| `sftp-download-file` | Stream a remote file to local disk, never through model context | — | ✅ |
| `signal-process` | Send INT/TERM/KILL to a remote PID | — | ✅ |

### Streaming file transfer

`sftp-upload`/`sftp-download` move file *contents* through the model's context:
the text is an argument on the way out and a response on the way back. That is
what you want for a config snippet and exactly what you do not want for a 200 MB
tarball or anything binary.

The two also differ on what they do to an existing destination, and the approved
string now says which is which. `sftp-upload` replaces unconditionally and spells
`--overwrite` every time, because that is what it always does; `sftp-upload-file`
refuses unless you pass `overwrite: true`, and only then carries the flag. Since
`sftp-upload` takes its content as an argument rather than naming a local file,
its string also carries `--bytes=<n> --sha256=<32 hex>` — without that, two
uploads to the same path are the same string, which means one approval covers
both and an auditor cannot tell which set of bytes landed. The digest is 128
bits rather than a short prefix because that claim has to hold against a caller
who picks both payloads, not only against an accidental repeat.

`[policy].denylist` patterns are tested against that whole string and, for every
SFTP tool, against the remote path on its own — as given, lexically normalized,
and read the way Windows reads it (see "Policy Engine"). A rule written for the
path, such as `authorized_keys$`, therefore does not depend on where the string
puts it or on how the file is spelled. A rule anchored on the *whole* string
(`^sftp:upload /root/.*$`) still does: that layout is ours to change, so anchor
on the path instead.

`sftp-upload-file` and `sftp-download-file` stream between the remote host and
local disk instead. Neither the bytes nor a base64 encoding of them ever reaches
the model — the response is a byte count and two paths.

The two transfer tools are **off until you configure `defaults.transferRoot`**,
and refuse with an explanation until then. (`sftp-list` has no local side and
needs none of this.) That directory is the whole of their local r