# Ssh Mcp

> MCP server for SSH operations with built-in diagnostics

- **Type:** MCP server
- **Install:** `agentstack add mcp-yawlabs-ssh-mcp`
- **Verified:** Pending review
- **Seller:** [YawLabs](https://agentstack.voostack.com/s/yawlabs)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [YawLabs](https://github.com/YawLabs)
- **Source:** https://github.com/YawLabs/ssh-mcp
- **Website:** https://yaw.sh/mcp-servers/ssh-mcp/

## Install

```sh
agentstack add mcp-yawlabs-ssh-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# @yawlabs/ssh-mcp

[](https://www.npmjs.com/package/@yawlabs/ssh-mcp)
[](https://opensource.org/licenses/MIT)

**Make SSH work for AI tools.** MCP server that manages your SSH environment, diagnoses what's broken, fixes it, and gives your agent remote access to anything.

Built and maintained by [Yaw Labs](https://yaw.sh).

[](https://yaw.sh/mcp/install?name=SSH&command=npx&args=-y%2C%40yawlabs%2Fssh-mcp&description=Run%20commands%20on%20remote%20hosts%2C%20transfer%20files%2C%20manage%20SSH%20tunnels%20and%20keys&source=https%3A%2F%2Fgithub.com%2FYawLabs%2Fssh-mcp)

One click adds this to your local Yaw MCP config so it's available in every Yaw Terminal session. Or install manually below.

## The problem

AI CLI tools run in subprocesses where SSH is constantly broken. The agent tries to `git pull` and gets `Permission denied (publickey)`. It tries to SSH into a server and the agent socket is stale. It tries to deploy and the host key changed because the instance was recreated. Every time, the AI has no idea what's wrong and spirals.

This happens across every situation that needs SSH keys:

- **Git** — clone, pull, push, fetch, submodules, LFS
- **Package managers** — `npm install`, `pip install`, `go get`, `cargo`, `composer` from private repos
- **Server access** — SSH, SCP, SFTP, rsync
- **Tunneling** — port forwarding to databases, SOCKS proxies
- **Deployment** — Ansible, Terraform, Capistrano, deploy scripts
- **Cloud** — AWS EC2, GCP, Azure, DigitalOcean, any VPS

**ssh-mcp** fixes this. It manages the SSH agent, loads keys, diagnoses failures with actionable fix commands, and provides remote operations — all as MCP tools your AI agent can call.

## Quick start

Add to your MCP client config:

```json
{
  "mcpServers": {
    "ssh": {
      "command": "npx",
      "args": ["-y", "@yawlabs/ssh-mcp@latest"]
    }
  }
}
```

On Windows wrap with `cmd /c` since Node 20+ can't spawn `.cmd` files directly:

```json
{
  "mcpServers": {
    "ssh": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@yawlabs/ssh-mcp@latest"]
    }
  }
}
```

The `@latest` tag makes `npx` re-resolve against the registry on every spawn, so each MCP session uses the newest published version. Or install globally if you'd rather pin (no auto-update):

```bash
npm install -g @yawlabs/ssh-mcp
# then in client config: "command": "ssh-mcp"
```

## Tools

### SSH environment management

Tools that fix your local SSH setup so everything else — git, deploys, tunnels — stops breaking.

| Tool | Description |
|------|-------------|
| `ssh_agent_ensure` | Ensure ssh-agent is running. Starts one if needed and sets env vars for the session. |
| `ssh_key_list` | List all SSH keys in ~/.ssh/ with type, fingerprint, and agent status. |
| `ssh_key_load` | Load a key into the running agent. Ensures the agent is started first. |
| `ssh_config_lookup` | Resolve the effective SSH config for a host (hostname, user, port, proxy, identity files). |
| `ssh_known_hosts_fix` | Remove a stale host key and re-scan. Fixes "host key verification failed" errors. |
| `ssh_git_check` | Test Git-over-SSH auth to GitHub, GitLab, Bitbucket, etc. |
| `ssh_test` | Quick connectivity test with timing and actionable error details. |

### Diagnostics

| Tool | Description |
|------|-------------|
| `ssh_diagnose` | Full SSH environment diagnostic. Checks agent, keys, config, known_hosts, and connectivity. Returns exact fix commands for every failure. |

### Remote operations

| Tool | Description |
|------|-------------|
| `ssh_exec` | Execute a command on a remote host. Returns stdout, stderr, and exit code (or `[signal: NAME]` and `code: -1` when the channel closed signal-only). Optional `env` param sets per-call environment variables (POSIX-safe prefix, works regardless of sshd's `AcceptEnv`). Subject to [command policy](#command-policy) if configured. |
| `ssh_read_file` | Read a file from a remote host via SFTP. |
| `ssh_write_file` | Write content to a file on a remote host via SFTP. |
| `ssh_upload` | Upload a local file to a remote host via SFTP. |
| `ssh_download` | Download a file from a remote host to local filesystem. |
| `ssh_ls` | List files in a directory on a remote host. |
| `ssh_stat` | Get metadata for a file or directory (size, mode in octal, uid/gid, mtime/atime, isFile/isDirectory/isSymbolicLink). Use instead of parsing `ls -la`. |
| `ssh_mkdir` | Create a directory via SFTP. Set `recursive: true` for `mkdir -p` behavior. Unlike the other SFTP tools, the path may be relative — it resolves against the SFTP working directory (normally the remote user's home). `~` is not expanded; SFTP has no shell. |
| `ssh_delete` | Delete a file or empty directory via SFTP. Auto-dispatches unlink vs rmdir based on the path's *own* type (`lstat`), so a symlink is always unlinked — never followed — including a dangling one or one pointing at a directory. Recursive directory delete is intentionally NOT supported -- use `ssh_exec rm -rf` if you need it. |

### Higher-level operations

Tools that wrap common patterns agents build with ssh_exec — faster and less error-prone.

| Tool | Description |
|------|-------------|
| `ssh_multi_exec` | Run a command on multiple hosts in parallel. Returns results per host. Optional `env` param sets per-call environment variables (same POSIX-safe prefix as `ssh_exec`, applied once and sent to every host). Subject to [command policy](#command-policy) if configured (policy is checked once, against the env-prefixed command, before fan-out). |
| `ssh_find` | Search for files remotely with structured parameters (`name`, `type`, `size`, `depth`, `newer` — match files modified more recently than a reference path). |
| `ssh_tail` | Read the last N lines of a file, optionally filtered by a grep pattern. |
| `ssh_service_status` | Check systemd service status (active, PID, uptime, description). Flags `isError` only when the unit could not be found / queried, not when an existing unit is intentionally stopped. |

### Auto-diagnostics

When any remote operation fails, ssh-mcp automatically runs diagnostics and includes the results in the error response. Your agent doesn't need to call `ssh_diagnose` separately — it gets told what's wrong and how to fix it right in the error message.

### Connection pooling

Remote operations reuse SSH connections automatically. When your agent makes multiple calls to the same host, the first call opens a connection and subsequent calls reuse it. Connections are kept alive for 60 seconds after the last use, then closed automatically.

The pool caps at 100 connections by default, and a connection still being dialed counts against the cap. When the cap is reached the pool closes an idle connection to make room. If every slot is in use or dialing, a tool call waits for one instead of failing:

- **A single-host remote tool** (`ssh_exec`, the SFTP tools, `ssh_find`, `ssh_tail`, `ssh_service_status`) waits up to its `timeout` (30s for the SFTP tools, which have no `timeout` parameter) and is next in line for the first slot that frees, so an `ssh_exec` arriving in the middle of a wide `ssh_multi_exec` runs between two of its hosts rather than being refused for the whole run. It reports `Connection pool is full` only if it never won a slot in that time.
- **`ssh_multi_exec`** runs at most `SSH_MCP_MAX_POOL_SIZE` hosts at once (default 100) and works through a longer list as slots free up, so raising the cap raises its parallelism; `timeout` is per host, not a bound on the whole call. When the pool is full it waits, and gives up only when none of its own hosts holds a slot and a full `timeout` has passed with none of them starting or finishing. The hosts waiting at that point (up to one per parallel slot) and every host still queued then report `Connection pool is full`; the queued ones are never attempted.

A call reaches `Connection pool is full` only when other calls — a long `ssh_exec`, a concurrent `ssh_multi_exec` — kept every slot from it for a full `timeout`; a fan-out wider than the cap that has the pool to itself never does, however long it runs. If you see it, rerun once those calls finish (for `ssh_multi_exec`, the hosts that reported it), or raise the cap with `SSH_MCP_MAX_POOL_SIZE=` in the server's environment. The error names the variable.

The library's `acquire()` / `withConnection()` do not wait by default: they reject at once with a `PoolFullError` (`code: "ERR_SSH_MCP_POOL_FULL"`, `isPoolFullError()`) unless you pass `{ waitForCapacityMs }` — see [Programmatic usage](#programmatic-usage).

### SSH config support

All connections respect your `~/.ssh/config`. Host aliases, custom ports, usernames, identity files, and ProxyJump settings are used automatically. If you have `Host myserver` configured in your SSH config, just pass `host: "myserver"` — ssh-mcp resolves everything.

**ProxyJump / bastion hosts** are supported automatically. If your SSH config has `ProxyJump bastion` for a host, ssh-mcp connects through the bastion transparently. Chained proxies work too.

### Host key verification

All remote operations verify the server's host key against `~/.ssh/known_hosts`:

- **Known host, key matches** — accept.
- **Known host, key changed** — reject (MITM protection). The rejection message distinguishes a genuine key mismatch from "the server offered a key type your `known_hosts` entry doesn't cover", so a missing ed25519 line doesn't read as an attack.
- **Unknown host** — accept, unless `SSH_MCP_STRICT_HOST_KEY=1`.

**That last branch is trust-always, not TOFU.** Real trust-on-first-use pins the key it saw the first time and rejects a change afterwards. The connection path never writes to `known_hosts` — no tool adds an entry as a side effect of connecting — so connecting pins nothing: *every* connection to a host absent from `known_hosts` is a "first" use and is accepted, including one where an attacker swapped the key since your last call. Only hosts put into `known_hosts` out of band get mismatch protection — by you, by `ssh-keyscan`, or by `ssh_known_hosts_fix`, the one tool here that does write the file. Call it explicitly to add an entry so future changes are caught.

For stricter environments, set `SSH_MCP_STRICT_HOST_KEY=1` to reject unknown hosts. Add them explicitly with `ssh_known_hosts_fix` first.

The diagnostic tools (`ssh_test`, `ssh_diagnose`) use `StrictHostKeyChecking=no` for their probe commands. Those probes only run `echo SSH_OK` — no credentials or data pass through — so the relaxed setting is safe for connectivity testing. Real operations always go through the `hostVerifier`.

### Command policy

`ssh_exec` and `ssh_multi_exec` accept free-form shell commands from the agent. For security-conscious deployments, you can restrict which commands run via two env vars, each accepting a comma-separated list of regex patterns:

- `SSH_MCP_COMMAND_WHITELIST` — if set, the command **must** match at least one pattern, else it's blocked.
- `SSH_MCP_COMMAND_BLACKLIST` — if set, the command **must not** match any pattern, else it's blocked.

When both are set, the command must pass both checks (whitelist first, then blacklist). When neither is set (the default), all commands are allowed.

Patterns are JavaScript regexes. Use `^` and `$` for anchored matches; otherwise patterns are treated as substring matches. Commas are the delimiter, so a literal comma in a pattern needs to be expressed as `\x2c` or via a character class.

```bash
# Read-only allowlist: only ls / df / cat / find / tail
SSH_MCP_COMMAND_WHITELIST="^ls( .*)?,^df( .*)?,^cat ,^find ,^tail "

# Block destructive ops even if your agent goes off-script
SSH_MCP_COMMAND_BLACKLIST="^rm ,^shutdown,^reboot,^mkfs,^dd if=,>\s*/dev/"
```

Blocked commands surface as a clear error mentioning which pattern (or which env var) rejected the call, so the agent can adapt rather than guess. Policy is enforced before the SSH connection opens — no remote process is started for a blocked command.

#### Scope: policy covers `ssh_exec` and `ssh_multi_exec` only

Every other tool runs unchecked. That splits into two very different cases.

The structured **read** tools are all exempt, but for two different reasons — they don't reach the remote the same way.

`ssh_find`, `ssh_tail` and `ssh_service_status` do build a shell command (`find`, `tail`, `systemctl`), but from typed parameters with every interpolated value shell-quoted, never from free-form agent input. They're exempt for ergonomics: a tight `^ls` whitelist would otherwise force you to allow `^find `, `^tail `, `^systemctl ` just to keep those tools working — defeating the point of a tight whitelist.

`ssh_ls`, `ssh_stat`, `ssh_read_file` and `ssh_download` build no command at all. They're pure SFTP (`readdir`, `stat`, `readFile`, `fastGet`), so — exactly like the mutating SFTP tools below — there is no command string for a regex to match, and these env vars could not gate them even if you wanted them to. They're grouped with the reads rather than flagged as a gap because they don't mutate remote state. One caveat: `ssh_download` is non-mutating on the **remote** only — it writes to whatever local path it's handed, and these env vars don't constrain that either.

**The SFTP tools that mutate remote state are also unchecked, and that is a genuine gap — not an ergonomics call.** `ssh_write_file`, `ssh_upload`, `ssh_mkdir`, and `ssh_delete` never build a shell command string, so a command-shaped regex has nothing to match. Concretely: `SSH_MCP_COMMAND_BLACKLIST="^rm "` does **not** stop `ssh_delete`, and `SSH_MCP_COMMAND_WHITELIST="^ls "` does **not** stop `ssh_write_file`. Closing this would need a separate path-policy mechanism, which this server deliberately does not have. If you must prevent remote mutation, drop those four tools from your MCP client's tool allowlist (or run a client that gates them) — these two env vars cannot do it.

#### Policy interaction with the `env` parameter (`ssh_exec`, `ssh_multi_exec`)

When `ssh_exec` or `ssh_multi_exec` is called with `env: { KEY: "value" }`, the values are injected as a `KEY='value' ...` shell prefix before the command (see the tool descriptions). **Policy is checked against the full prefixed command**, not the bare `command` argument — once, before fan-out, in the `ssh_multi_exec` case. That's the safer ordering at the protocol layer — but it means whitelist patterns need to anticipate the prefix and must be **anchored**, not substring matches:

```bash
# WRONG -- blocks any ssh_exec call that uses `env`, because the final command
# starts with `KEY='value' ` and never matches `^ls`.
SSH_MCP_COMMAND_WHITELIST="^ls "

# RIGHT -- allow zero or more `KEY='value' ` prefixes before the real command.
SSH_MCP_COMMAND_WHITELIST="^([A-Za-z_][A-Za-z0-9_]*='[^']*' )*ls( |$)"
```

You don't have to diagnose this from a bare rejection: when a whitelist blocks a call that used `env`, the error appends a note explaining that the prefix is why the `^` anchor stopped matching, and suggests the tolerant pattern above.

**Avoid substring-match patterns** like ` ls ` if you're worried about a hostile agent. An agent could pass `env: { ATTACK: " ls " }` to make the final command `ATTACK=' ls ' rm -rf /`, which matches a substring ` ls ` and bypasses the whitelist. Anchored patterns of the form above don't have this weakness because they require the real command name to follow the env-prefix block, not appear inside a quoted env value.

Blacklists need the same care. `^rm ` blocks a bare `rm` call, but doesn't block `FOO='bar' rm`. Use the same env-prefix-tolerant anchor:

```bash
SSH_MCP_COMMAND_BLACKLIST="^([A-Za-z_][A-Za-z0-9_]*='[^']*' )*rm( |$)"
```

If you don't trust the agent's `env` values at all, the simplest mitigation is to leave `env` unused in your client config and pass everything through the `command` string yourself.

### Windows support

On Windows, ssh-mcp uses the OpenSSH Authentication Agent's `\\.\pipe\openssh-ssh-ag

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [YawLabs](https://github.com/YawLabs)
- **Source:** [YawLabs/ssh-mcp](https://github.com/YawLabs/ssh-mcp)
- **License:** MIT
- **Homepage:** https://yaw.sh/mcp-servers/ssh-mcp/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-yawlabs-ssh-mcp
- Seller: https://agentstack.voostack.com/s/yawlabs
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.