SSH MCP Server

io.github.YawLabs由 GitHub 账号 YawLabs 发布v0.19.0更新于 Nov 22, 2026

MCP server for SSH operations with built-in diagnostics

概览

AI 生成的概览

本地 MCP 服务器,让助手通过 SSH 在远程主机上执行命令、传输文件,并内置 SSH 诊断能力。

可以做什么
  • 在远程主机上执行 shell 命令,或在多台主机上并行执行同一命令
  • 通过 SFTP 读取、写入、上传、下载、列出、查看属性、创建和删除远程文件与目录
  • 搜索远程文件、按 grep 模式查看日志尾部、查询 systemd 服务状态
  • 检查并修复本地 SSH 环境:agent 状态、密钥列出与加载、配置查询、连通性测试、Git over SSH 检查
  • 诊断连接、认证与主机密钥故障,操作失败时自动附带诊断结果
适用场景
适合助手需要运维服务器、在远程机器上部署或查看日志,或在用户本机排查 SSH 与 Git over SSH 问题的场景。也适合需要在多台机器上批量执行同一命令的任务。
运行要求
以 npm 包形式在本地运行(npx 或全局安装),需要 Node.js;Windows 上需用 cmd /c 包裹 npx 命令。依赖本机 OpenSSH 配置:~/.ssh/config、ssh-agent(Windows 为 OpenSSH 代理管道)和 known_hosts。远程主机需网络可达。可选设置包括 SSH_MCP_MAX_POOL_SIZE、SSH_MCP_STRICT_HOSTKEYS、SSH_MCP_COMMAND_WHITELIST 和 SSH_MCP_COMMAND_BLACKLIST。
安装前请注意
助手可执行任意远程 shell 命令,并可写入、上传或删除远程文件;命令白名单与黑名单只约束 ssh_exec 和 ssh_multi_exec,不约束 SFTP 写入与删除工具。ssh_upload 会读取进程可读的任意本地文件,ssh_download 会写入助手指定的本地路径。未设置 SSH_MCP_STRICT_HOSTKEYS 时未知主机会被直接信任,ssh_known_hosts_fix 会改写 known_hosts。支持密码认证,但更推荐使用密钥。

安装

在 SourceWeft 中

  1. 打开 控制台中的 SSH MCP Server,将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only,通过 STDIO。 STDIO 服务会启动本地进程,因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

@yawlabs/ssh-mcp

[Add to Yaw 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.

[npm version] [License: 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.

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.

ToolDescription
ssh_agent_ensureEnsure ssh-agent is running. Starts one if needed and sets env vars for the session.
ssh_key_listList all SSH keys in ~/.ssh/ with type, fingerprint, and agent status.
ssh_key_loadLoad a key into the running agent. Ensures the agent is started first.
ssh_config_lookupResolve the effective SSH config for a host (hostname, user, port, proxy, identity files).
ssh_known_hosts_fixRemove a stale host key and re-scan. Fixes "host key verification failed" errors.
ssh_git_checkTest Git-over-SSH auth to GitHub, GitLab, Bitbucket, etc.
ssh_testQuick connectivity test with timing and actionable error details.

Diagnostics

ToolDescription
ssh_diagnoseFull SSH environment diagnostic. Checks agent, keys, config, known_hosts, and connectivity. Returns exact fix commands for every failure.

Remote operations

ToolDescription
ssh_execExecute 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_fileRead 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_fileWrite content to a file on a remote host via SFTP.
ssh_uploadUpload a local file to a remote host via SFTP.
ssh_downloadDownload a file from a remote host to local filesystem.
ssh_lsList files in a directory on a remote host.
ssh_statGet metadata for a file or directory (size, mode in octal, uid/gid, mtime/atime, isFile/isDirectory/isSymbolicLink). Use instead of parsing ls -la.
ssh_mkdirCreate 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_deleteDelete 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.

ToolDescription
ssh_multi_execRun 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_findSearch for files remotely with structured parameters (name, type, size, depth, newer — match files modified more recently than a reference path).
ssh_tailRead the last N lines of a file, optionally filtered by a grep pattern.
ssh_service_statusCheck 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.

This is a guard rail, not a security boundary. A regex over a string that a remote shell will interpret can catch an agent going off-script; it cannot contain a hostile one. It covers only ssh_exec and ssh_multi_exec: the SFTP tools are not gated at all (see Scope). An agent that also has a shell and the credential can bypass any control in this server. If you need a real boundary, enforce it on the remote host: a restricted account, a forced command in authorized_keys, sudo rules, or filesystem permissions.

Patterns are JavaScript regexes. Use ^ and $ for anchored matches; otherwise patterns are treated as substring matches. Commas separate patterns, except a comma inside a character class ([,]), an escaped comma (\,), or one in a {m,n} quantifier, which all stay part of the pattern. Any other literal comma, including one inside a group, must be written \,, [,] or \x2c. In a list of more than one pattern, write a literal comma as \, ([a\,b]) rather than [,]: an unescaped comma in a class is refused whenever another entry follows, so ^foo[,]bar$ works alone but must be ^foo[\,]bar$ (or kept as its own single-pattern variable) beside ^df$.

A malformed entry blocks everything. If any entry in either variable fails to compile, every ssh_exec and ssh_multi_exec call is refused with an error naming the entry, until you fix or unset the variable. The same applies to a character class that may have swallowed a separator: a class holding an unescaped comma is refused when its content suggests a swallowed separator (an unescaped [ before the comma, or a letter, digit, _, ^, [ or another comma after it) or when another entry follows the class, because ^rm[,^reboot,^mkfs[.] and ^rm[abc,>],^df would otherwise compile as one pattern and stop blocking reboot and rm. Escape the stray bracket as \[, or write a literal comma as \, ([a\,b]). This catches likely typos and is not a proof: ^rm[,>] still reads as one class.

bash
# Allowlist: list directories, check disk space and uptime. Each pattern covers the whole line.SSH_MCP_COMMAND_WHITELIST='^ls( [A-Za-z0-9_./:=@%+-]+)*$,^df( -[A-Za-z]+)*$,^uptime$'
# Denylist: best effort only. Catches the obvious spellings of these commands, nothing more.SSH_MCP_COMMAND_BLACKLIST='^rm ,^shutdown,^reboot,^mkfs,^dd if=,>\s*/dev/'

While a whitelist is active, a matching command is still refused if it:

  • contains shell control syntax anywhere, even inside quotes: ; & | a backtick $( ${ $[ @{ ( ) < > or a line break. Quotes are not interpreted because the remote login shell is unknown and shells disagree about them. So grep 'a|b' file is refused too, and so is git show HEAD@{1}, because @{ runs code in PowerShell.
  • starts with a variable assignment, such as LD_PRELOAD=/tmp/x.so ls or PATH=/tmp ls. This includes the prefix built from the env parameter.

Set SSH_MCP_COMMAND_ALLOW_SHELL_SYNTAX=1 (or true) to turn both checks off and go back to pattern-only matching. Each pattern is then responsible for the entire command, so anchor it at both ends as in the example above. Any value other than 1, true, 0, false or empty is rejected as a misconfiguration.

Choosing what to allow. Only allow programs that cannot run other programs or write files with the arguments you permit. These look read-only and are not:

  • find runs commands and deletes files (-exec, -execdir, -ok, -delete, -fprint).
  • awk runs commands (system(), | getline) and writes files.
  • tar runs commands (--checkpoint-action=exec=..., --to-command, --use-compress-program).
  • sed (e command, w), xargs, env, sudo, ssh, git (-c, aliases, hooks), less and vim can also launch programs.
  • cat, tail and head run nothing, but read any file the account can read, including keys and credentials.

A whitelist only sees the command text, so a broad pattern such as ^find allows all of the above.

Denylists are best effort. The same command has endless spellings: ^rm misses /bin/rm, \rm, r''m, command rm, busybox rm, and anything run through sh -c or a script. Pipes to curl and similar exfiltration need no denied word at all. Use a denylist to catch mistakes, never as the control that keeps something from happening.

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, and it has two effects under a whitelist.

env is refused by default while a whitelist is active. A variable such as LD_PRELOAD or PATH changes what an allowed command actually runs, so the prefix counts as a leading assignment (see above). Remove env from the call. A ^ls pattern will not match the prefixed string in any case, and the rejection explains why.

If you must allow a specific variable, set SSH_MCP_COMMAND_ALLOW_SHELL_SYNTAX=1 and write a pattern that names the variable and spells out the whole command. Never use a generic variable-name pattern, which would admit LD_PRELOAD and PATH:

bash
SSH_MCP_COMMAND_ALLOW_SHELL_SYNTAX=1SSH_MCP_COMMAND_WHITELIST="^FOO='(?:[^']|'\\\\'')*' ls( [A-Za-z0-9_./:=@%+-]+)*$"

(That is the double-quoted shell form. The regex itself is ^FOO='(?:[^']|'\\'')*' ls( [A-Za-z0-9_./:=@%+-]+)*$, which is what belongs in a JSON env block after JSON escaping.)

Avoid substring-match patterns like ls. An agent could pass env: { ATTACK: " ls " } to make the final command ATTACK=' ls ' some-other-command, which contains ls. The assignment check refuses that by default, but some-other-command ls would still match, so anchor every pattern.

Blacklists see the prefix too. ^rm blocks a bare rm call, but doesn't block FOO='bar' rm. An env-tolerant anchor closes that one spelling, and like every denylist it stays best effort:

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

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.21.1 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 prefers oam (auto); to rule the runtime out when agent auth fails there, set SSH_MCP_RUNTIME=node. 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 used to be broken on oam 0.20.2; that is fixed as of 0.21.1 — see oam key support.

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:

ParameterDescriptionDefault
hostSSH hostname or IP (required)—
portSSH portFrom SSH config or 22
usernameSSH usernameFrom SSH config or current user
privateKeyPathPath to SSH private keyAuto-detect
passwordSSH 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.

  1. Explicit privateKeyPath — used alone. The agent is not offered and no other key is read.
  2. Explicit password — used alone, same as above.
  3. 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 loadedAgent 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 unreachableAgent reports: "SSH server isn't running on new-server or port 22 is blocked"

Programmatic usage

typescript
import { connect, exec, diagnose, ensureAgent, listSshKeys, checkGitSsh, ConnectionPool, isPoolFullError } from '@yawlabs/ssh-mcp';
// Fix SSH environmentconst agent = ensureAgent();console.log(agent.message);
// Check git accessconst git = checkGitSsh('github.com');console.log(git.message);
// List available keysconst keys = listSshKeys();for (const key of keys) {  console.log(`${key.name} (${key.type}) - ${key.loadedInAgent ? 'loaded' : 'not loaded'}`);}
// Run a remote command (one-off)const client = await connect({ host: 'my-server', username: 'deploy' });const result = await exec(client, 'uptime');console.log(result.stdout);client.end();
// Run multiple commands with connection poolingconst pool = new ConnectionPool();await pool.withConnection({ host: 'my-server' }, async (client) => {  const r1 = await exec(client, 'uptime');  console.log(r1.stdout);});// Connection stays open for 60s — next call reuses itawait pool.withConnection({ host: 'my-server' }, async (client) => {  const r2 = await exec(client, 'df -h');  console.log(r2.stdout);});// A full pool rejects at once with a PoolFullError; pass a budget to wait for a slot// instead, the way the tools do, and match the rejection on its code, not its texttry {  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(); // close all connections when done
// Diagnose issuesconst report = diagnose('my-server');console.log(report.overall); // "ok" | "warning" | "error"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. The default runtime, auto, prefers the newest usable oam and falls back to Node when there is none. The minimum is the latest oam release, currently 0.21.1, and the launcher never serves on an older oam.

The default prefers oam again as of oam 0.21.1, which closed the node:crypto gaps it used to trip over: an ed25519 key file, an ECDSA key file, an ed25519-only server and curve25519 key exchange all work there. It was Node-only for one release line (0.18.4-0.18.6), while oam 0.20.2 was the floor; those four gaps are tracked in YawLabs/oam#489, now closed.

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) — prefer oam. On a Node host the launcher discovers the newest usable oam and spawns it, falling back to Node in-process when none is found. Started by oam at or above the floor it serves in-process, with no second oam. Started by oam below the floor it hands off to Node on PATH (or to a newer oam), or exits with status 1 when there is neither; 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.21.1 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.21.1 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.21.1, 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 an oam 0.21.1 or newer serves the server itself, in the same process, with no note about unusable key types -- the gap that used to earn one is closed. An oam below the floor never serves there: it hands off to Node on PATH, or to the newest usable oam it can find, or exits with status 1 when there is neither.
  • With SSH_MCP_RUNTIME=oam on oam 0.21.1 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.

oam key support

oam 0.21.1 supports ed25519 and ECDSA key files, servers whose only host key is ed25519, and curve25519 key exchange in ssh2. Measured through the launcher on oam 0.21.1 (oam run bin/ssh-mcp.mjs): MCP initialize, tools/list (the same 21 tools as on Node) and tools/call on ssh_key_list, ssh_config_lookup and ssh_agent_ensure; and against a local ssh2 server, identical to Node 22, an ed25519 key file, an ECDSA key file, an ed25519-only host key and curve25519-sha256 all complete an exec, with ssh2's probes reporting eddsaSupported = true and curve25519Supported = true. An ed25519 key held in the agent was not measured end to end; what used to block it was ssh2 failing to parse an ed25519 public key on oam, and the underlying crypto.verify gap is closed.

The four node:crypto gaps that used to break these on oam 0.20.2 -- a crypto.verify that threw on an Ed25519 private key (which is how ssh2 decides it supports ed25519), a missing crypto.diffieHellman, x25519 key pairs that could not be generated, and SEC1 (EC PRIVATE KEY) signing that threw -- are listed in the launcher's comments and were tracked in YawLabs/oam#489, now closed.

To pin Node regardless of what the default prefers:

json
{  "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: oam 0.21.1+ (preferred by auto when a usable one is installed) — see Runtime selection

License

MIT

[Follow @YawLabs on X]

来源:README.md,提交 4dcc4c7

工具

21

ssh_exec

Execute a command on a remote host via SSH. The command is interpreted by the remote login shell — pipes, redirects, globs, and other shell metacharacters work as expected. Returns up to three content blocks in this order: the status (`[exit code: N]`, plus the signal and any truncation), then `[stderr]`, then `[stdout]`. Status comes first so a proxy that cuts long results (Yaw MCP keeps about 100 KB) never drops the exit code; for big output, filter or page on the remote (head, tail, grep). Use `env` to set environment variables for this call without modifying the command string. Subject to SSH_MCP_COMMAND_WHITELIST / SSH_MCP_COMMAND_BLACKLIST if configured (policy is checked against the env-prefixed command). While a whitelist is active, shell control syntax and leading variable assignments are refused unless the server sets SSH_MCP_COMMAND_ALLOW_SHELL_SYNTAX=1. Policy is a best-effort guard rail, not a security boundary.

输入参数envhost必填portcommand必填timeoutpasswordusernameprivateKeyPath

ssh_read_file

Read a file from a remote host via SFTP. A whole-file read is limited to 10 MB. For a large file -- or behind a proxy that caps results, such as Yaw MCP at about 100 KB -- read it in pages with `offset` and `length` (bytes): a paged read returns a status block first (`[bytes A-B of SIZE]` and the next offset) and then the text. If the connection pool is full (SSH_MCP_MAX_POOL_SIZE, default 100), waits up to 30s for a free slot before starting.

输入参数host必填path必填portlengthoffsetpasswordusernameprivateKeyPath

ssh_write_file

Write content to a file on a remote host via SFTP. Creates or overwrites the file. If the connection pool is full (SSH_MCP_MAX_POOL_SIZE, default 100), waits up to 30s for a free slot before starting. NOT gated by SSH_MCP_COMMAND_WHITELIST / SSH_MCP_COMMAND_BLACKLIST: command policy applies only to the remote command-execution tools (single-host and multi-host), so a blacklist such as `^rm` does NOT block this tool.

输入参数host必填path必填portcontent必填passwordusernameprivateKeyPath

ssh_upload

Upload a local file to a remote host via SFTP. Reads an arbitrary local file at an agent-chosen `localPath` -- any file readable by this process leaves the machine toward the remote host (the mirror direction of a download, which writes an arbitrary local file). If the connection pool is full (SSH_MCP_MAX_POOL_SIZE, default 100), waits up to 30s for a free slot before starting. NOT gated by SSH_MCP_COMMAND_WHITELIST / SSH_MCP_COMMAND_BLACKLIST: command policy applies only to the remote command-execution tools (single-host and multi-host), so a blacklist such as `^rm` does NOT block this tool.

输入参数host必填portpasswordusernamelocalPath必填remotePath必填privateKeyPath

ssh_download

Download a file from a remote host to local filesystem via SFTP. If the connection pool is full (SSH_MCP_MAX_POOL_SIZE, default 100), waits up to 30s for a free slot before starting.

输入参数host必填portpasswordusernamelocalPath必填remotePath必填privateKeyPath

ssh_ls

List files in a directory on a remote host via SFTP. If the connection pool is full (SSH_MCP_MAX_POOL_SIZE, default 100), waits up to 30s for a free slot before starting.

输入参数host必填path必填portpasswordusernameprivateKeyPath

ssh_stat

Get metadata for a file or directory on a remote host via SFTP. Returns size, permissions (octal), uid/gid, mtime/atime, and the path type. Symlinks are reported as `symlink -> <target kind>`: the type describes the link itself while size/mode/mtime describe its TARGET, and a dangling symlink is reported rather than erroring. Use this instead of parsing `ls -la` output. If the connection pool is full (SSH_MCP_MAX_POOL_SIZE, default 100), waits up to 30s for a free slot before starting.

输入参数host必填path必填portpasswordusernameprivateKeyPath

ssh_mkdir

Create a directory on a remote host via SFTP. Set `recursive: true` to create parent directories as needed (like `mkdir -p`). Existing intermediate dirs are tolerated; an existing leaf path is still an error. Unlike the other SFTP tools, the path may be relative. If the connection pool is full (SSH_MCP_MAX_POOL_SIZE, default 100), waits up to 30s for a free slot before starting. NOT gated by SSH_MCP_COMMAND_WHITELIST / SSH_MCP_COMMAND_BLACKLIST: command policy applies only to the remote command-execution tools (single-host and multi-host), so a blacklist such as `^rm` does NOT block this tool.

输入参数host必填path必填portpasswordusernamerecursiveprivateKeyPath

ssh_delete

Delete a file or empty directory on a remote host via SFTP. Auto-detects the path type and calls the right SFTP op (unlink for files/symlinks, rmdir for empty dirs). Recursive directory delete is intentionally NOT supported -- for that, run `rm -rf` explicitly as a remote shell command so the destructive intent is visible in the tool trace. If the connection pool is full (SSH_MCP_MAX_POOL_SIZE, default 100), waits up to 30s for a free slot before starting. NOT gated by SSH_MCP_COMMAND_WHITELIST / SSH_MCP_COMMAND_BLACKLIST: command policy applies only to the remote command-execution tools (single-host and multi-host), so a blacklist such as `^rm` does NOT block this tool.

输入参数host必填path必填portpasswordusernameprivateKeyPath

ssh_diagnose

Diagnose SSH connectivity issues. Checks ssh-agent status, loaded keys, known_hosts, SSH config, and attempts a test connection. Use this BEFORE attempting SSH operations if you suspect connectivity issues, or AFTER a failed SSH operation to understand why it failed.

输入参数host必填port

ssh_agent_ensure

Ensure ssh-agent is running and reachable. Starts a new agent if needed and sets environment variables so subsequent SSH operations work. Use this FIRST when SSH operations fail with agent-related errors.

无需输入参数。

ssh_key_list

List all SSH private keys in ~/.ssh/ with their type, fingerprint, and whether they are loaded in the agent. Use this to find which keys are available and which ones need to be loaded. Reports isError only when ~/.ssh exists but could not be read -- an absent or empty ~/.ssh is a successful answer with a ssh-keygen hint.

无需输入参数。

ssh_key_load

Load an SSH private key into the running agent. Ensures the agent is running first. Use this after listing local keys shows one that is not loaded.

输入参数keyPath必填

ssh_config_lookup

Resolve the effective SSH configuration for a host. Shows hostname, user, port, identity files, proxy settings, and all other options from ~/.ssh/config. Use this to understand how SSH will connect to a host.

输入参数host必填

ssh_known_hosts_fix

Remove a stale host key from known_hosts and re-scan the host to add the current key. Use this when you see 'Host key verification failed' errors, typically after a server has been recreated or reprovisioned.

输入参数host必填port

ssh_test

Quick connectivity test to an SSH host. Reports success/failure with timing and actionable error details. Lighter and faster than a full SSH environment diagnosis — use this for a quick check before running operations.

输入参数host必填port

ssh_git_check

Test Git-over-SSH authentication to a hosting provider (GitHub, GitLab, Bitbucket, etc). Verifies your SSH key is registered and working. Use this when git clone/pull/push fails with SSH errors.

输入参数hostuser

ssh_multi_exec

Execute a command on multiple remote hosts in parallel. Runs at most SSH_MCP_MAX_POOL_SIZE hosts at once (default 100) and works through a longer list as slots free up. `timeout` is per host: it bounds each host's command, not the whole call. Each parallel slot works through its share of the list one host at a time, so with the pool to itself a call can take up to about ceil(hosts / SSH_MCP_MAX_POOL_SIZE) x (`timeout` + connect time). The connection pool is shared with every other tool; when it is full this call waits for slots instead of failing, 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. Rerun those hosts once the other calls finish, or raise SSH_MCP_MAX_POOL_SIZE. Returns results per host. Use this instead of running the same command against each host one call at a time — it's faster and shows results side by side. Use `env` to set environment variables for this call without modifying the command string. Subject to SSH_MCP_COMMAND_WHITELIST / SSH_MCP_COMMAND_BLACKLIST if configured (policy is checked once, against the env-prefixed command, before fan-out). While a whitelist is active, shell control syntax and leading variable assignments are refused unless the server sets SSH_MCP_COMMAND_ALLOW_SHELL_SYNTAX=1. Policy is a best-effort guard rail, not a security boundary.

输入参数envporthosts必填command必填timeoutpasswordusernameprivateKeyPath

ssh_find

Search for files on a remote host. Wraps the find command with structured parameters so you don't have to construct find syntax manually.

输入参数host必填namepath必填porttypenewermaxsizeminsizetimeoutmaxdepthpasswordusername另有 1 个

ssh_tail

Read the last N lines of a file on a remote host, optionally filtering by a grep pattern. Use this for reading log files instead of running tail/grep by hand as a remote shell command.

输入参数grephost必填path必填portlinestimeoutpasswordusernameprivateKeyPath

ssh_service_status

Check the status of a systemd service on a remote host. Returns whether it's active, its PID, uptime, and description. Use this instead of running systemctl as a remote shell command.

输入参数host必填portservice必填timeoutpasswordusernameprivateKeyPath

版本历史

10
  1. v0.19.0最新Nov 21, 2026
  2. v0.18.6Nov 16, 2026
  3. v0.18.4Nov 16, 2026
  4. v0.18.2Nov 12, 2026
  5. v0.18.1Oct 31, 2026
  6. v0.18.0Oct 11, 2026
  7. v0.17.3Oct 7, 2026
  8. v0.17.2Oct 7, 2026
  9. v0.17.1Sep 30, 2026
  10. v0.17.0Sep 16, 2026

评分

已满足适用检查项的 90%

该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分
  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头,或保持端点能够响应探测,以便判定其认证方式。

  • 已列出工具必需15 分
  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分