@yawlabs/ssh-mcp

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

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.
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:
{
"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:
{
"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):
npm install -g @yawlabs/ssh-mcp
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 up to three content blocks, status first: [exit code: N] (plus [signal: NAME] with code: -1 when the channel closed signal-only, and a flag when a stream hit the 10 MB cap), then [stderr], then [stdout]. Status leads so a proxy that cuts long results โ Yaw MCP keeps about 100 KB by default โ never drops the exit code. Optional env param sets per-call environment variables (POSIX-safe prefix, works regardless of sshd's AcceptEnv). Subject to command policy if configured. |
ssh_read_file | Read a file from a remote host via SFTP (whole file up to 10 MB). Optional offset and length (bytes) read one page and return a [bytes A-B of SIZE; next offset: N] status block before the text โ use them for a large file, or behind a proxy that caps results. |
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 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=<n> 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.
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 strict mode is on (
SSH_MCP_STRICT_HOSTKEYS=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_HOSTKEYS=1 (or true, case-insensitive) to reject unknown hosts. Add them explicitly with ssh_known_hosts_fix first. The older name SSH_MCP_STRICT_HOST_KEY still works and accepts the same values, but prefer the new one: credential scanners such as Yaw MCP's doctor treat any name with a _KEY segment as a secret, and flag the old name as a plaintext credential.
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.
SSH_MCP_COMMAND_WHITELIST="^ls( .*)?,^df( .*)?,^cat ,^find ,^tail "
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:
SSH_MCP_COMMAND_WHITELIST="^ls "
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:
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-agent named pipe automatically when SSH_AUTH_SOCK is not set. No SSH_AUTH_SOCK needed โ just make sure the OpenSSH agent service is running.
On the oam runtime, the launcher serves only on oam 0.20.2 or newer. Agent auth needs a net that can dial a named pipe or a Unix socket (that is how ssh2 reaches the agent), which older oam releases could not do. On oam 0.20.2 (Windows) the MCP handshake, ssh_config_lookup, ssh_key_list and ssh_agent_ensure were verified through the launcher, and ssh2's own agent client was verified dialing a named pipe and completing an identities request (against a stand-in agent on a pipe). An agent-only ssh_exec end to end has so far been verified on Node only. Started from Node, the launcher only uses oam when asked to (SSH_MCP_RUNTIME=oam); if agent auth fails there, unset it to rule the runtime out. Started by oam with no Node on PATH, it can still serve on oam: see Runtime selection. ed25519 and ECDSA keys and ed25519-only servers do not work on oam 0.20.2 at all โ see Known limits on oam 0.20.2.
ssh_agent_ensure and ssh_diagnose probe that pipe and tell you if the service is down. Remote operations do not: they assume the pipe and let the connection fail on its own if the agent isn't there. That is why a stopped agent service shows up as an auth failure rather than an "agent not running" error until you run the diagnostic tools.
Authentication
All remote operations accept connection parameters:
| Parameter | Description | Default |
|---|
host | SSH hostname or IP (required) | โ |
port | SSH port | From SSH config or 22 |
username | SSH username | From SSH config or current user |
privateKeyPath | Path to SSH private key | Auto-detect |
password | SSH password (prefer keys) | โ |
Auth resolution. An explicit credential wins outright and nothing else is offered. With neither given, ssh-mcp offers the ssh-agent and one on-disk key together โ the way the OpenSSH client does โ and lets the server pick during the auth exchange. It is not a strict first-match chain past step 2.
- Explicit
privateKeyPath โ used alone. The agent is not offered and no other key is read.
- Explicit
password โ used alone, same as above.
- Neither given โ both of the following are configured on the same connection:
- ssh-agent โ
SSH_AUTH_SOCK, or on Windows the \\.\pipe\openssh-ssh-agent named pipe. The Windows pipe is assumed unconditionally; ssh-mcp does not check that the OpenSSH Authentication Agent service is actually running.
- One on-disk key โ the first readable path in
ssh -G <host>'s identityfile list. OpenSSH emits that list for every host, including one with no IdentityFile line (it defaults to ~/.ssh/id_rsa, id_ecdsa, id_ecdsa_sk, id_ed25519, id_ed25519_sk), so this is the normal path โ not a path reserved for hosts you configured an identity for. ssh-mcp's own built-in list (~/.ssh/id_ed25519, id_rsa, id_ecdsa) is a fallback used only when ssh -G cannot run at all, e.g. no SSH client installed.
Two things worth knowing about step 3:
- Only one on-disk key is ever offered โ the first candidate that exists. ssh-mcp does not walk the whole identity list the way
ssh does, so if the first readable key is the wrong one, authentication rests on the agent's keys. Pass privateKeyPath to force a specific key.
- When an agent is configured, an encrypted on-disk key is skipped and the scan moves to the next candidate. The underlying ssh2 library parses
privateKey eagerly and errors with "no passphrase given" on an encrypted key, which would break the common setup of an encrypted key on disk with its decrypted copy loaded in the agent. With no agent configured, the first existing key is loaded regardless of encryption and ssh2 surfaces the passphrase error itself. Because the Windows pipe above is assumed unconditionally, the skip is always in force on Windows.
Example workflows
Agent can't git pull
Agent calls ssh_git_check โ "Permission denied. Your SSH key is not registered with github.com."
Agent calls ssh_key_list โ finds id_ed25519 exists but is not loaded
Agent calls ssh_key_load("~/.ssh/id_ed25519") โ "Key loaded"
Agent calls ssh_git_check โ "Git SSH authentication to github.com succeeded as username"
Agent runs git pull โ works
Host key changed after instance recreation
Agent calls ssh_exec on server โ error: "Host key verification failed"
(auto-diagnostics included in error: "Fix with ssh_known_hosts_fix")
Agent calls ssh_known_hosts_fix("my-server") โ "Host key refreshed"
Agent calls ssh_exec โ works
First-time connection to a new server
Agent calls ssh_test("new-server") โ "Connection refused at new-server:22"
Agent calls ssh_diagnose("new-server") โ full report showing agent running, keys loaded, but host unreachable
Agent reports: "SSH server isn't running on new-server or port 22 is blocked"
Programmatic usage
import { connect, exec, diagnose, ensureAgent, listSshKeys, checkGitSsh, ConnectionPool, isPoolFullError } from '@yawlabs/ssh-mcp';
const agent = ensureAgent();
console.log(agent.message);
const git = checkGitSsh('github.com');
console.log(git.message);
const keys = listSshKeys();
for (const key of keys) {
console.log(`${key.name} (${key.type}) - ${key.loadedInAgent ? 'loaded' : 'not loaded'}`);
}
const client = await connect({ host: 'my-server', username: 'deploy' });
const result = await exec(client, 'uptime');
console.log(result.stdout);
client.end();
const pool = new ConnectionPool();
await pool.withConnection({ host: 'my-server' }, async (client) => {
const r1 = await exec(client, 'uptime');
console.log(r1.stdout);
});
await pool.withConnection({ host: 'my-server' }, async (client) => {
const r2 = await exec(client, 'df -h');
console.log(r2.stdout);
});
try {
await pool.withConnection(
{ host: 'other-server' },
async (client) => {
const r3 = await exec(client, 'uptime');
console.log(r3.stdout);
},
{ waitForCapacityMs: 30_000 },
);
} catch (err) {
if (!isPoolFullError(err)) throw err;
console.log('no slot within 30s:', err.message);
}
pool.drain();
const report = diagnose('my-server');
console.log(report.overall);
for (const check of report.checks) {
console.log(`[${check.status}] ${check.name}: ${check.message}`);
}
Runtime selection
The ssh-mcp command โ what npx @yawlabs/ssh-mcp runs โ is a small launcher. It runs the server on Node by default. The oam runtime is opt-in, with SSH_MCP_RUNTIME=oam; its minimum is the latest oam release, currently 0.20.2, and the launcher never serves on an older oam.
The default used to prefer oam whenever a usable one was installed. It is Node until oam closes the node:crypto gaps tracked in YawLabs/oam#489: on oam 0.20.2 ed25519 and ECDSA key files and ed25519-only servers do not work (see Known limits on oam 0.20.2).
Two environment variables control the choice; set them in your MCP client's env block:
SSH_MCP_RUNTIME โ which runtime to use. Case-insensitive, surrounding whitespace ignored; any value other than oam or node behaves as auto.
auto (default) โ Node. Started from Node, the launcher does not look for oam, and if OAM_BIN is set it says on stderr that it was not used. Started by oam, it hands off to Node on PATH and serves on oam only when there is none; see the list below.
oam โ require oam. Fails loudly: if no usable oam is found, the launcher prints what it found and why each one was passed over to stderr, and exits with status 1 instead of starting the server.
node โ always Node. The launcher does not look for oam, and OAM_BIN is ignored.
OAM_BIN โ with SSH_MCP_RUNTIME=oam, path to an oam binary to use in preference to discovery, when it is 0.20.2 or newer. If it does not exist, is older, will not run, or does not answer --version with oam's own oam x.y.z banner (another program's version, such as Node's v22.x.y, does not count), the launcher says so on stderr and carries on with discovery.
Discovery (under SSH_MCP_RUNTIME=oam) looks in $OAM_INSTALL_DIR (when set โ the oam installer's install target), then %LOCALAPPDATA%\oam\bin (Windows only), then ~/.oam/bin, then every directory on PATH; asks every oam binary it finds for its version, counting only an answer that carries oam's own oam x.y.z banner; and uses the newest one at 0.20.2 or newer. On a tie the one found first wins, so an installed copy beats one on PATH. On Windows only oam.exe counts: an oam.cmd/oam.bat shim on PATH is never run, and is named on stderr when no usable oam is found.
With SSH_MCP_RUNTIME=oam an unusable oam is an error: the launcher names on stderr each oam (and OAM_BIN) it passed over and why โ older than 0.20.2, not runnable, or a shim โ or the chosen oam that failed to start, and exits with status 1. It does not fall back to Node.
When the launcher is itself started by oam (oam run <path>/bin/ssh-mcp.mjs, which is how Yaw MCP starts an npx @yawlabs/ssh-mcp entry when a recent oam is installed):
- In
auto mode it hands the server off to Node on PATH, whatever the oam version, and says so on stderr. Only when there is no Node on PATH does oam serve: an oam 0.20.2 or newer runs the server itself, in the same process, with a note on stderr that the key types under Known limits will not work; an older oam hands off to the newest usable oam it can find, or exits with status 1.
- With
SSH_MCP_RUNTIME=oam on oam 0.20.2 or newer, it runs the server on that oam, in the same process. Nothing is discovered or spawned, and OAM_BIN is not read: that oam is the one required. On an older oam it never runs the server there; it hands off to the newest usable oam it can find, or exits with status 1.
- With
SSH_MCP_RUNTIME=node it hands the server off to Node on PATH, whatever the oam version, and exits with status 1 when there is none.
Whenever an oam host starts a child (the handoffs above), the launcher removes --permission and --allow-* flags from the child's inherited NODE_OPTIONS. oam (since 0.18.0) adds its own permission flags to every child's NODE_OPTIONS, and Node refuses some of them there (--allow-net is not allowed in NODE_OPTIONS, exit 9); this server is not sandboxed, so there is nothing to pass on. An oam that was itself started with --permission re-adds the flags inside spawn(), which the launcher cannot undo, so do not start it that way.
Known limits on oam 0.20.2
Four node:crypto gaps in oam 0.20.2 are behind these, tracked in YawLabs/oam#489:
crypto.verify throws when it is given an Ed25519 private key. ssh2 decides whether it supports ed25519 by signing and then verifying with a private key, so on oam it turns ed25519 off altogether. oam itself can generate ed25519 keys, sign with them and verify with the public key; this one call is what disables ed25519 in ssh2.
crypto.diffieHellman does not exist, so ssh2 does not offer curve25519 key exchange.
- x25519 key pairs cannot be generated, which curve25519 key exchange would need as well.
- Signing with a SEC1 (
EC PRIVATE KEY) key throws, and that is the form ssh2 converts an ECDSA key file to before signing.
Measured with this package's ssh2 against a local ssh2 server, each case below works on Node 22 and fails on oam 0.20.2:
- An ed25519 private key file โ the connection is refused before it starts:
Cannot parse privateKey: Unsupported OpenSSH private key type: ssh-ed25519. This applies to the key file ssh-mcp picks up on its own (the first usable IdentityFile, or ~/.ssh/id_ed25519) as well as to privateKeyPath, and it fails the connection even when an agent is also offered.
- An ECDSA private key file โ authentication fails:
Error signing data with key: SEC1 EC private key format not supported; use PKCS#8.
- A server whose only host key is ed25519 โ
Handshake failed: no matching host key format.
- An ed25519 key held in the agent โ ssh2 cannot parse an ed25519 public key on oam (
Unsupported key format), so it is not expected to be usable; this one was not measured end to end.
What was measured working on oam 0.20.2: password auth and an RSA private key file, against servers with an RSA or ECDSA host key, over ecdh-sha2-nistp256 (curve25519 key exchange is not offered).
This is why the default runtime is Node. The launcher does not check for any of it when you opt in: with SSH_MCP_RUNTIME=oam, or an MCP client that starts oam run .../dist/index.js itself, the cases above fail as listed.
The default will go back to preferring oam once an oam release handles these cases. To pin Node regardless of what a later release defaults to:
{
"mcpServers": {
"ssh": {
"command": "npx",
"args": ["-y", "@yawlabs/ssh-mcp@latest"],
"env": { "SSH_MCP_RUNTIME": "node" }
}
}
}
On Windows, add the same env block to the cmd /c form from Quick start.
Requirements
- Node.js 18+
- SSH client installed (for diagnostics and environment management)
- Optional, opt-in: oam 0.20.2+ โ see Runtime selection
License
MIT
