fast-mcp-ssh

An MCP server that gives a model real SSH access: one connection per host kept alive across calls, a PTY shell that remembers cd and export, SFTP instead of cat > file, host-to-host copies that never touch your disk, a screenshot of the remote desktop, regex guards before anything leaves your machine, and an append-only audit log. Answers come back as TOON, roughly 40 percent fewer tokens than JSON on tabular data.

Install

cargo install fast-mcp-ssh

Or take a prebuilt binary from the latest release and check it against the matching .sha256. Linux and macOS ship x86_64 and aarch64, Windows ships x86_64.

Copy hosts.example.toml to ~/.fast-mcp-ssh/hosts.toml and fill in your hosts. Keys go in ~/.fast-mcp-ssh/keys/<name>; auth is key, agent or password.

Related MCP server: Shuttle

Wire it up

.mcp.json, or claude_desktop_config.json for Claude Desktop:

{
  "mcpServers": {
    "ssh": {
      "type": "stdio",
      "command": "fast-mcp-ssh"
    }
  }
}

In the MCP registry it is mcp-name: io.github.klNuno/fast-mcp-ssh.

Tools

host is optional on every tool once [defaults] default_host is set.

Every tool carries MCP annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) so a client can gate destructive calls.

Security

• Guards run before any SSH packet. deny_patterns refuse outright, confirm_patterns trigger an MCP elicitation, and a client that cannot elicit is denied. read_only = true blocks anything that looks like a write.

• Paths are checked on both sides. Remote reads of keys, shadow files and cloud credentials are refused, and so are local writes that would land in your ~/.bashrc or an autostart folder. Paths are re-checked after the server resolves them, so a symlink cannot launder a blocked target.

• Host keys are pinned (TOFU by default, strict and per-host fingerprints available). Every call is appended to ~/.fast-mcp-ssh/audit.log as NDJSON, with credentials scrubbed.

Guards are a speed bump against accidents, not a boundary against an adversary who controls the model. Scope the remote account accordingly: full threat model in SECURITY.md.

Benchmark

50 iterations per scenario against the same Linux host over the same LAN, same SSH key, bench client on Windows 11. Medians, lower is better. Reproduce with benchmark/; raw runs in benchmark/results/.

Both alternatives are Node processes, so ~250 ms of their cold start is the runtime booting. The steady-state gap is the connection: fast-mcp-ssh keeps one SSH session per host and spawns a channel per call, while the other two reconnect. Writes go over SFTP here and through a cat > file heredoc there.

returning the same output. ssh-mcp-server returns raw stdout with no exit code, which is why its replies are the shortest and why a failed command looks like a successful one.

Development

cargo install --path .        # build and install from a clone
cargo test                    # unit tests
cargo clippy --all-targets    # no warnings allowed in CI
./scripts/test-sh.ps1         # end-to-end against a real host (Windows)

Never write to stdout outside the MCP transport: a stray println! corrupts the JSON-RPC stream and the client disconnects without an error. tracing macros go to stderr and are safe.

License

MIT.