Skip to main content
Glama

ssh-remote

常驻 SSH 长连接的 MCP server。让 WorkBuddy / Cursor 这类 AI 编码工具直接读写远端机器、执行远端命令,而不是每次调用都新建一次 SSH 连接。

装上之后的效果,和「本地连上远程开发机干活」基本一致:搜代码、读文件、改文件、跑命令、跑长任务、TTY 交互,都在远端原生环境里完成。

为什么要它

Windows 上每次 ssh host "cmd" 的开销拆开看:

环节

耗时

创建新进程(疑似杀软实时扫描)

~480ms

SSH 握手

~420ms

网络往返(局域网 <1ms)

可忽略

也就是说真正的命令执行时间被开销完全淹没了。而 Windows 上两个 ssh 实现都不支持连接复用:

  • Git-MSYS:mux_client_request_session: read from master failed: Connection reset by peer

  • Win32-OpenSSH:getsockname failed: Not a socket

所以 ~/.ssh/config 里配 ControlMaster 是没用的。

本项目的解法:绕开 multiplexing,改成一个常驻 Node 进程 hold 住一条 ssh2 连接,通过 MCP 暴露工具。调用时不创建进程、不重新握手。

Related MCP server: mcp-ssh-terminal

实测性能

同刻对照,Windows 本机:

方式

一次典型四步信息收集¹

ssh 命令行(4 次调用)

3339ms

本 MCP(4 次工具调用)

177ms

约 19 倍。单次调用:ssh 稳定 825ms,本MCP exec 50ms / search 52ms / list 82ms / read 8ms / stat 3ms。

¹ git 状态 + 代码搜索 + 读文件 + 健康检查

长连接会发心跳(15s × 3 次容错),跑完6 分钟的全量测试后健康检查仍是 14ms。首连含建连226ms,属一次性成本。

安装

npm install

在 MCP 客户端的配置里注册(WorkBuddy 是 ~/.workbuddy/mcp.json):

{
  "mcpServers": {
    "ssh-remote": {
      "command": "node",
      "args": ["<绝对路径>/ssh-remote/server.js"],
      "env": {
        "SSH_REMOTE_HOST": "192.168.0.110",
        "SSH_REMOTE_USER": "yourname",
        "SSH_REMOTE_BASE": "/home/yourname/work/yourproject"
      }
    }
  }
}

必填 SSH_REMOTE_HOST / SSH_REMOTE_USER / SSH_REMOTE_BASE;不填会在启动时直接报错并告诉你怎么配,而不是拿着空主机名去连、报一堆看不懂的 ssh 错误。

新 server 需要在客户端的连接器管理里 Trust,并重启客户端才会加载。

Windows + Git Bash 的坑

在 Git Bash 里手动跑验证脚本时,MSYS 会把环境变量值里的 Unix 路径改写成 Windows 路径:

# ✗ SSH_REMOTE_BASE 传进 node 后变成了 C:/Program Files/Git/home/... → "No such file"
SSH_REMOTE_BASE=/home/me/proj node smoke-test.js

# ✓
MSYS_NO_PATHCONV=1 SSH_REMOTE_BASE=/home/me/proj node smoke-test.js

走 MCP 配置(JSON)启动不受影响——那条路径不经过 shell。

配置

变量

必填

说明

SSH_REMOTE_HOST

✅

目标主机地址

SSH_REMOTE_PORT

SSH 端口,默认 22

SSH_REMOTE_USER

✅

登录用户名

SSH_REMOTE_KEY

私钥路径,默认 ~/.ssh/id_ed25519

SSH_REMOTE_BASE

✅

远端工作目录,必须是绝对路径

SSH_REMOTE_HOME

~ 展开的基准,默认 /home/$SSH_REMOTE_USER

SSH_REMOTE_BASE 必须是绝对路径:它会被拼进远端 cd "...",双引号里 ~ 不做展开。所有工具的相对路径都基于它。

换机器:改env 段,重启客户端。多台机器并行:复制一份目录,在配置里注册第二个条目、换个名字(工具前缀随之区分,如 mcp__ssh-remote-2__*)。同一台机器不需要多个 server。

免密登录:把公钥放进目标机~/.ssh/authorized_keys(ssh-copy-id)。

工具

工具

用途

remote_exec

执行远端命令。多条命令用 && 串成一次调用更省——成本在调用次数,不在命令条数

remote_exec_bg

后台起长任务,立即返回 jobId,不阻塞

remote_job_check

查任务状态(running / done / failed)、退出码、耗时、日志尾部

remote_job_list

列出远端所有任务

remote_read

读远端文件(带行号)

remote_write

写远端文件(整文件覆写)

remote_replace

精确字符串替换,改文件不必整篇重写

remote_search

远端全文搜索(rg,跨连接复用)

remote_find

按名找文件(fd)

remote_list

列目录

remote_stat

文件元信息

remote_health

连接健康检查

后台长任务

长跑的东西(全量测试、构建、大批量迁移)不该占着 MCP 调用不放:

remote_exec_bg({ command: "make test-db", label: "全量测试" })
// → { jobId: "muw9a36u-e6taf", pid: "2523963" }   约 250ms 返回

remote_job_check({ jobId: "muw9a36u-e6taf" })
// → { status: "done", exitCode: 0, durationMs: 226000, log: "..." }

状态全放远端 /tmp/ssh-remote-jobs/<jobId>/,所以客户端重启也能继续查(内存状态会随进程消失,进度条就没意义了)。日志不会进 git,也不会被任何目录遍历工具扫到。

边界与取舍

  • 没有 GUI diff 视图 / 变更文件面板。原生 Read/Grep 只认本地路径,这是本机侧的限制。但git diff 本身能通过 remote_exec 完整拿到,AI 读文本足够。

  • 改文件是整文件覆写或精确替换,没有「光标停在某行」的细粒度编辑。对 AI 干活够用。

  • 单条 TCP:网络抖动会让正在跑的长命令直接失败(下一跳自动重连,但这一跳会报错)。长任务建议用 remote_exec_bg。

  • 输出有上限:命令 1MB、文件 512KB、目录 500 项,超出截断。

  • 依赖远端有 rg / fd:remote_search / remote_find 需要。没装会明确报错,退回 grep 也行,只是慢。

TTY 交互

server 是非交互的,但远端有 tmux,所以 TTY 程序能跑:

tmux new-session -d -s htop htop
tmux capture-pane -pt htop     # 抓屏看内容

curses 程序、长跑任务中途看进度都适用。

验证改动

改完代码不必重启客户端就能验——探针会新建子进程加载最新代码:

node mcp-probe.js        # 跑通全部工具 + 后台任务三件套
node smoke-test.js       # 量化握手开销vs 连接复用
node bg-selftest.js      # 拿真实长任务验「起任务不阻塞」

安全边界

目标主机由 CONFIG 固定,工具参数无法指定别的主机——不提供任意目标跳转能力。stdout 专供 MCP 协议,所有日志走 stderr。

Available Tools

12 tools
remote_execB

在远端服务器执行命令。默认工作目录是 SSH_REMOTE_BASE 指定的目录。把多条命令用 && 串成一次调用更省时间——成本在调用次数,不在命令条数。

Inputs: command (required), cwd, timeout.

remote_exec_bgA

后台起一个远端任务,立即返回不等待。适合编译、全量测试、构建镜像这类几分钟的活——返回 jobId,之后用 remote_job_check 查结果。任务状态存在远端文件系统上,本工具重启、甚至 WorkBuddy 重启后照样能接着查。

Inputs: command (required), cwd, name.

remote_findA

在远端按文件名查找(走 fd-find,缺失时回退 find)。比 remote_list 递归快得多。

Inputs: pattern (required), path, type, maxResults.

remote_healthA

查看 SSH 长连接状态;断线时会自动重连一次。

Inputs: no named parameters.

remote_job_checkA

查一个后台任务的状态与输出。返回 running / done / failed,终态时带退出码和日志末尾若干行。

Inputs: jobId (required), tail.

remote_job_listB

列出当前所有后台任务,含在跑的和已结束的(按开始时间倒序)。

Inputs: all.

remote_listB

列出远端目录内容,返回类型、大小、修改时间。

Inputs: path, maxEntries.

remote_readB

读取远端文件。支持按行区间读取,返回带行号以便后续精确修改。

Inputs: path (required), endLine, maxBytes, startLine.

remote_replaceB

在远端文件里做精确字符串替换,无需传整个文件。old_string 必须唯一匹配,否则报错——这是为了防止改错地方。

Inputs: path (required), newString (required), oldString (required), replaceAll.

remote_statB

查看远端文件或目录是否存在及其属性(类型、大小、修改时间、权限)。

Inputs: path (required).

remote_writeB

整文件写入远端。改大文件前建议先 remote_read 确认内容。

Inputs: path (required), content (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 12 tools

    Disambiguation4/5

    Tools are largely distinct: remote_list (single dir), remote_find (recursive by name), remote_search (by content), and remote_stat (specific path properties) have clearly different scopes, and exec vs exec_bg vs job_check/list are well separated. There is mild overlap in the cluster of 'inspect the filesystem' tools, but descriptions disambiguate them adequately.

    Naming Consistency5/5

    Every tool uses a consistent remote_ prefix followed by a clear verb or verb_noun suffix (remote_list, remote_read, remote_write, remote_exec_bg, remote_job_check). The pattern is predictable throughout with no convention mixing.

    Tool Count5/5

    12 tools is well within scope for a remote file-and-exec server, and each tool covers a distinct operation (listing, searching, reading, writing, replacing, executing, background jobs, health). No redundancy or padding.

    Completeness4/5

    Core file lifecycle (read, write, replace) plus search, exec, and background-job management are covered, but there is no explicit delete, mkdir, or move/rename operation. These gaps are workaround-able via remote_exec shell commands, so they are minor rather than blocking.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to maintain persistent SSH terminal sessions and transfer files to/from remote servers. Allows stateful command execution, natural language server management, and seamless file operations through SSH connections.
      10 npm
      35
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to have persistent, fully interactive SSH sessions into remote hosts, behaving like a local terminal.
      14 npm
      2
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI assistants to run shell commands, read, write, edit, search, and stream files on remote SSH servers and Docker containers, including nested multi-layer chains, without installing any runtime on the target hosts. It auto-injects a self-contained Go helper with adaptive zstd compression for fast transfers and process control.
      9
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables coding agents on Windows clients to operate on Unix file servers through one long-lived SSH session per host, running exec/view/create/edit/grep/glob with POSIX paths and shell state (cd, env) persisting across calls. Bypasses slow or flaky SMB/CIFS mounts entirely, giving native-speed file operations without drive letters or remounts.
      19,226 npm
      MIT