fast-mcp-ssh

fast-mcp-ssh

为 AI Agent 提供 SSH、SFTP 和持久化 Shell。单个 Rust 二进制文件，无需运行时。

一个为大模型提供真正 SSH 访问能力的 MCP 服务：

• 每台主机保持一个连接，并在调用之间持续打开。
• 记住 cd 和 export 状态的 PTY Shell。
• 使用 SFTP，而非 cat > file；主机间复制不会经过你的磁盘。
• 远程桌面的屏幕截图。
• 在任何内容离开你的机器之前进行正则表达式检查。
• 记录每次调用的仅追加审计日志。

结果以 TOON 格式返回；对于表格数据，使用的令牌比 JSON 少约 40%。

安装

cargo install fast-mcp-ssh

也可以从最新版本获取预构建二进制文件，并使用 SHA256SUMS.txt 校验。Linux 和 macOS 提供 x86_64 和 aarch64 版本，Windows 提供 x86_64 版本。

将 hosts.example.toml 复制到 ~/.fast-mcp-ssh/hosts.toml，并填写主机信息。密钥放在 ~/.fast-mcp-ssh/keys/<name> 中；auth 可设置为 key、agent 或 password。

配置连接

.mcp.json，或者 Claude Desktop 使用的 claude_desktop_config.json：

{
  "mcpServers": {
    "ssh": {
      "type": "stdio",
      "command": "fast-mcp-ssh"
    }
  }
}

同一配置块也适用于 Claude Code、Cursor、Windsurf、Zed、VS Code Copilot，以及其他任何通过 stdio 使用 MCP 的工具。

在 MCP 注册表中的名称为 mcp-name: io.github.klNuno/fast-mcp-ssh。

工具

设置 [defaults] default_host 后，所有工具中的 host 参数均为可选。

分组	工具
运行	exec exec_batch sh interrupt	单次执行、并行扇出、持久化 PTY、Ctrl-C
文件	ls stat dn up cp wr mkdir rm tail	SFTP，以及在有界窗口中执行 tail -n / tail -F
可视化	shot	截取远程桌面，并在发送给大模型前缩小图像
运维	facts sys svc	缓存的主机概况、解析后的 ps/df/mem/net、systemd 单元
会话	hosts ping disconnect disconnect_all reload shells	发现与生命周期管理；reload 无需重启即可替换配置，shells 会关闭指定名称的 PTY
网络	forward unforward forwards	通过同一连接建立本地 TCP 转发

每个工具都带有 MCP 注解（readOnlyHint、destructiveHint、idempotentHint、openWorldHint），客户端可据此限制破坏性调用。

主机间复制

cp 可将文件从一台已配置的主机传到另一台。文件内容不会落到你的磁盘上，也不会发送给大模型；操作成功前，两端都会比对 sha256。目标端同样受检查规则约束，因此只读目标仍会拒绝写入。

远程屏幕截图

shot 会将图像而非大段文本交给大模型。它会使用主机上可用的 grim、gnome-screenshot、spectacle、ImageMagick import 或 scrot，支持 X11 和 wlroots Wayland，并在本地缩小图像，避免 4K 屏幕产生数 MB 的载荷。

协议

支持无状态 MCP（2026-07-28）以及此前的所有版本，直至 2024-11-05， 并根据对端选择版本。无状态模式有三项变化：

• 确认操作会返回 input_required 结果，由客户端作答并重试（SEP-2322）， 因为服务端可能无法再主动发起请求。较旧的对端仍使用 elicitation/create。
• 耗时调用会返回一个任务句柄供轮询（SEP-2663）：超过 60 秒超时的 exec， 以及使用 follow=true 的 tail。不支持此扩展的客户端仍会执行阻塞调用。
• tools/list 会排序，因此每次重启后的字节内容都相同，并带有一小时的 ttlMs（SEP-2549）。客户端的提示词缓存会持续命中。

Shell 不受影响。PTY 一直通过调用的 host 和 session 参数寻址；这正是无状态模式所需的显式句柄。

安全

任何 SSH 数据包发出前都会运行防护规则。deny_patterns 会直接拒绝， confirm_patterns 会询问用户；无法作答的客户端会被拒绝，read_only = true 则会拦截任何看起来像写入的操作。

路径会在两端检查：远程读取密钥、shadow 文件和云凭据，以及向本地 ~/.bashrc 或自动启动文件夹写入。每个接受路径参数的工具都会执行这两项检查， 包括 tail；服务端解析路径后还会再次检查，因此无法通过符号链接绕过被拦截的目标。 无法解析的路径会导致调用被拒绝。

主机密钥会被固定；默认采用 TOFU，也可使用 strict 和按主机配置的指纹。 每次调用都会以 NDJSON 格式记录到 ~/.fast-mcp-ssh/audit.log，并清除凭据。

防护规则能避免意外操作，但无法抵御控制模型的攻击者。请相应限定远程账户的权限。 威胁模型：SECURITY.md。 版本历史：CHANGELOG.md。

基准测试

每种场景运行 50 次，使用同一台 Linux 主机、同一局域网、同一 SSH 密钥，客户端运行于 Windows 11。以下为中位数，越低越好；测量版本为 0.5.0。可通过 benchmark/ 复现，原始运行结果位于 benchmark/results/。

	fast-mcp-ssh	mcp-ssh-manager	ssh-mcp-server
冷启动	48 ms	280 ms	260 ms
exec echo ok	2.2 ms	89.7 ms	46.7 ms
exec uname -a; whoami; pwd	3.6 ms	90.9 ms	50.6 ms
exec seq 1 5000（约 29 KB）	19.6 ms	90.4 ms 1	49.2 ms
写入 1 KB 文件	1.1 ms	89.9 ms	47.9 ms
读取 1 KB 文件	1.7 ms	90.3 ms	48.9 ms
每个会话都要发送的工具列表	26 个工具，21.1 KB	37 个工具，39.9 KB	4 个工具，1.7 KB

另外两个方案都使用 Node，因此其冷启动时间中约有 250 ms 是运行时启动所需。 稳态性能差异来自连接方式：fast-mcp-ssh 为每台主机保持一个 SSH 会话，并为每次调用打开一个通道；另外两个方案则会重新连接。 这里的写入通过 SFTP 完成，那里则通过 cat > file heredoc 完成。

开发

cargo install --path .        # build and install from a clone
cargo test                    # unit tests
cargo clippy --all-targets    # no warnings allowed in CI
./scripts/test-sh.ps1         # end-to-end against a real host (Windows)

除 MCP 传输外，切勿向 stdout 写入内容：意外的 println! 会破坏 JSON-RPC 流，导致客户端断开连接且不报错。tracing 宏会将内容写入 stderr，因此可以安全使用。

许可证

MIT。

Footnotes

1. mcp-ssh-manager 会将该响应截断至 12 KB，因此返回的输出并不相同。 ssh-mcp-server 会返回原始 stdout，但不包含退出代码，因此它的回复最短， 失败的命令也会看起来像是成功执行。 ↩