ssh-bridge-mcp

让 Claude Code / Codex / Claude Desktop 通过 MCP 统一操作局域网 Linux 的 SSH 桥。本机常驻一个 MCP server（Node + @modelcontextprotocol/sdk + ssh2），把 SSH 封装成结构化工具；LLM 侧永远只看到工具与输出，看不到配置文件、看不到密码。

Claude Desktop / Claude Code / Codex
        |  MCP (stdio)
        v
本机 Windows 上运行的 MCP server (Node + @modelcontextprotocol/sdk + ssh2)
        |  SSH（密码来自本地配置）
        v
多台远程 Linux（配置文件里列出）

快速开始

1. npm install

2. 复制 config.example.json 为 config.json 并填写主机与密码（sudoPassword 缺省同 password）

   {
     "default": "dev01",
     "hostKeyPolicy": "insecure",
     "localRoots": ["<allowed-local-dir>"],
     "maxDownloadBytes": 2147483648,
     "hosts": {
       "dev01": {
         "host": "<remote-host-ip>",
         "port": 22,
         "user": "<username>",
         "password": "<ssh-password>",
         "sudoPassword": "<sudo-password>"
       }
     }
   }

3. 启动：npm start（或用 SSH_BRIDGE_CONFIG=/path/to/config.json npm start 指定配置路径）

配置文件默认在项目根目录 config.json，可用环境变量 SSH_BRIDGE_CONFIG 覆盖。配置文件内容在工具输出中永不出现。

hostKeyPolicy 与 localRoots 都是可选的加固项，默认关闭（自用局域网 + 本地虚拟机场景）。不想要就直接删掉那两行，见「安全边界」。maxDownloadBytes 默认 2 GiB，只在你要传更大的文件时才需要动。

Related MCP server: ssh-client-mcp-server

接入

Claude Desktop

在 claude_desktop_config.json 增加：

{
  "mcpServers": {
    "ssh-bridge": {
      "command": "node",
      "args": ["<path-to>/ssh-bridge-mcp/src/server.js"]
    }
  }
}

Claude Code

claude mcp add ssh-bridge -- node <path-to>/ssh-bridge-mcp/src/server.js

工具

run_command 参数：host / command / cwd / timeout_ms / sudo / pty / env / input。host 可省略，缺省连配置的默认主机。

安全边界

本项目默认面向自用局域网 + 本地虚拟机：两项校验默认关闭，不打扰开发。需要时按下面的开关打开，启动时若两项都没开会在 stderr 提示一次。

主机密钥校验

ssh2 在没有 hostVerifier 时接受任意主机密钥（见 ssh2 README：Default: (auto-accept if hostVerifier is not set)）——也就是谁在那个 IP 上应答，密码就交给谁。策略由 hostKeyPolicy 决定：

tofu 与本地虚拟机重建这种场景是冲突的：VM 重建会换主机密钥，连接会被拒到你把那一行删掉。频繁重建的 VM 就别开，或者用 hostKeyFingerprint 钉。

• 可信密钥存放于 known_hosts（OpenSSH 格式，默认在 config.json 同目录；knownHosts 可指定路径或路径数组，第一个是写入目标）。若 ~/.ssh/known_hosts 存在，会一并只读参与匹配，所以你在 Git Bash 里连过的主机不用重新录。

• knownHosts 和 localRoots 里的相对路径按 config.json 所在目录解析（不是进程 cwd——那个由拉起 server 的客户端决定）。

• 预置密钥直接照抄 OpenSSH 的习惯：

  ssh-keyscan -p 22 <remote-host-ip> >> known_hosts

• 不想用 known_hosts 的话，按主机钉指纹："hostKeyFingerprint": "SHA256:..."（ssh-keygen -lf 的输出）。这一项与 hostKeyPolicy 无关，配了就生效。

• @revoked 条目会被硬拒；@cert-authority 不支持，也会被拒（不会偷偷降级成 tofu）。

• 密钥变了就报错并列出新旧指纹：主机确实重装过，删掉 known_hosts 里那一行再连。

本机路径边界

upload / download 的本机路径由模型传入，没有边界时被 prompt injection 的 agent 可以把本机任意文件（含 config.json 里的明文密码）传到远程主机，或用 download 覆盖本机任意路径。localRoots（目录数组，可选）用来把范围圈住：

• 不配 = 不限制（默认，开发时最省事）；配了就只允许这些目录。

• 比较前先解析真实路径（symlink 逃不出去），Windows 下大小写不敏感，.. 和同名前缀的兄弟目录都会被拒。

• 配了不存在的目录会启动报错并列出实际解析到的绝对路径。

另外有一条始终生效、不可关闭：配置文件本身永远不可传输。它零成本（没人需要把自己的凭据库传到虚拟机上），且正好是上面那条泄露路径的入口。

传输大小上限

download 在传第一个字节之前先 stat 远端文件，超过 maxDownloadBytes 就拒绝，默认 2 GiB（0 = 不限制）。这是防「远端把本机磁盘写满」，不是防大文件——50 MB ~ 1 GB 这类正常传输不受影响，实测 50 MB 文件约 47 MB/s 且逐字节一致。

拒了就把 maxDownloadBytes 调大；限额是配置项而不是硬编码，正是为了不挡住正当的大文件。传完还会核对本地文件字节数与远端声明的一致，写少了会报错而不是当成功返回。

算法套件

ssh2 自己的默认提议列表本来就是现代的——CBC、3DES、arcfour、ssh-dss、sha1 系列密钥交换只在它的 "supported" 列表里，不主动提议。所以默认列表里唯一过时的东西是 SHA-1，本 server 把它减掉：

• serverHostKey 去掉 ssh-rsa（SHA-1 签名方案）

• hmac 去掉 hmac-sha1 与 hmac-sha1-etm@openssh.com

用的是 ssh2 的 remove 操作，从默认列表里做减法，所以 ssh2 的能力探测仍然生效，不会出现「请求了本机 crypto 不支持的算法」而直接抛错。实测发出去的 KEXINIT 为：

serverHostKey: ssh-ed25519, ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, ecdsa-sha2-nistp521, rsa-sha2-512, rsa-sha2-256
mac          : hmac-sha2-256-etm@openssh.com, hmac-sha2-512-etm@openssh.com, hmac-sha2-256, hmac-sha2-512

• 要按主机自定义就写 algorithms（ssh2 的格式：精确数组，或 append / prepend / remove 对象；对象形式会与上面的减法合并，数组形式则整体替换该组）。

• 遇到只支持 ssh-rsa 的老设备，写 "allowLegacyAlgorithms": true 恢复 ssh2 的完整默认提议。

sudoPassword 缺省等于 password（见 src/config.js）：sudo 与 SSH 共用同一个密码时，一台主机失守就等于那台机器 root 失守。密码不同的话显式写 sudoPassword。

使用说明（面向 agent）

本 MCP 的所有能力通过以下约定使用，避免命令拼接错误：

1. 环境变量

• env 参数注入，不要手拼 FOO=bar cmd 或 export FOO=bar && cmd。

  run_command(command: "npm test", env: { NODE_ENV: "test", DEBUG: "1" })

2. 多行命令

• command 传多行字符串即脚本，作为单个参数交给 bash -c 执行，支持 heredoc。注意外层 shell 不保留 cd —— 多条命令用 && 串联。

  run_command(command: "cd /app && npm ci && npm run build")

• heredoc 通过 <<'EOF' 避免变量展开：

  run_command(command: "cat > /tmp/x.sh <<'EOF'\necho keep_literal\nEOF\nbash /tmp/x.sh")

3. sudo 提权

• 需要 root 时设 sudo: true，server 自动喂密码。不要手写 echo password | sudo。

  run_command(command: "apt-get update && apt-get install -y python3", sudo: true)

4. 命令失败与超时

• 命令非零退出不会抛异常，返回真实 exit code。检查 exitCode 而不是捕获异常。

• 超过 timeout_ms 返回 timeout 状态，考虑拆短命令或改用 start_background。

5. 文件操作

• 文本/小文件：read_file / write_file（UTF-8，自动建目录）。read_file 上限 500 KB。

• 大文件/二进制/整个目录：upload / download（SFTP 流式，路径不经 shell，无转义问题）。

• 本地路径是本机 Windows 路径，远程路径是目标 Linux 路径，勿混淆。

• 配了 localRoots 时本机路径必须在其中，越界会被拒绝——那是策略，不是权限故障，别改成别的路径重试。

6. 长驻进程

• dev server、训练等长驻任务用 start_background，返回 task_id，用 background_logs 增量看日志，stop_background 终止。

• 后台进程池仅限当前客户端进程，Claude Desktop 起的进程 Codex 看不到。

7. 常用开发组合（示意）

• 跑测试：run_command(command: "npm test", cwd: "/project")

• git 提交（多行消息）：run_command(command: "git commit -F -", input: "feat: 新增 X\n\n- a\n- b")

• 查看日志：run_command(command: "journalctl -u myapp --no-pager -n 50", sudo: true)

• 构建并部署：run_command(command: "npm ci && npm run build && ./deploy.sh")