realssh-mcp

SSH Real MCP 服务

一个模型上下文协议（MCP）服务，可通过完全委托给系统 ssh 二进制文件来执行 SSH 远程命令。这意味着 ssh-agent、ProxyCommand、~/.ssh/config、跳板主机以及其他所有操作系统级 SSH 功能都能开箱即用——无需 Node.js 加密功能或原生插件。

工作原理

此服务不会在 Node.js 中实现 SSH 协议，而是将 ssh 作为子进程启动，并将输出传回 MCP 客户端。身份验证、密钥发现和连接路由均由操作系统处理，效果与在终端中自行运行 ssh 完全相同。

**要求：**必须安装 ssh，且可在 PATH 中找到（macOS 和 Linux 通常都已预装）。

功能

• 无需配置身份验证 — 自动使用现有的 ssh-agent、~/.ssh/config 和密钥文件
• ProxyCommand / 跳板主机 — 原生支持，无需特殊参数
• 连通性测试 — 使用 ssh_test 工具在运行命令前验证是否可连接
• 防止参数注入 — 将主机和用户名传给 ssh 前会进行验证
• 可配置超时 — 如果命令运行时间超过超时时限，将终止命令并返回错误
• 详细结果：标准输出、标准错误和退出代码

安装

从 npm 安装

npm install -g @danielecr/realssh-mcp

从源码安装

git clone https://github.com/danielecr/realssh-mcp.git
cd realssh-mcp
npm install
npm run build

VS Code / Copilot 配置

全局安装软件包后，将服务添加到 MCP 配置中。在 VS Code 中，通过命令面板 → MCP: Open User Configuration打开 MCP 配置文件并添加：

{
  "servers": {
    "realssh": {
      "type": "stdio",
      "command": "realssh-mcp"
    }
  }
}

然后运行 MCP: List Servers，确认服务已启用。

工具

ssh_execute

通过 SSH 在远程服务上执行命令。

参数：

• host（字符串，必填）：SSH 服务主机名或 IP 地址
• command（字符串，必填）：要在远程服务上执行的命令
• username（字符串，可选）：SSH 用户名。默认为当前操作系统用户
• port（数字，可选）：SSH 服务端口（默认值：22）
• timeout（数字，可选）：命令超时时间，单位为毫秒（默认值：30000）
• agentForward（布尔值，可选）：启用 SSH Agent 转发 -A（默认值：false）
• extraArgs（字符串数组，可选）：额外的 SSH 参数（例如：["-o", "StrictHostKeyChecking=no"]）

示例：

{
  "host": "prod-web-01",
  "command": "df -h"
}

{
  "host": "192.168.1.100",
  "username": "deploy",
  "command": "systemctl status nginx"
}

ssh_test

测试与远程主机的 SSH 连通性（运行 echo ok 并检查响应）。

参数：

• host（字符串，必填）：SSH 服务主机名或 IP 地址
• username（字符串，可选）：SSH 用户名
• port（数字，可选）：SSH 服务端口（默认值：22）
• extraArgs（字符串数组，可选）：额外的 SSH 参数

主机配置

主机、别名、跳板主机和身份文件都在 ~/.ssh/config 中配置，而不是在 MCP 服务中配置。这是有意为之：操作系统的 ssh 二进制文件会原生读取该文件。

~/.ssh/config 示例：

Host prod
    HostName prod.example.com
    User deploy
    ProxyJump bastion

Host bastion
    HostName bastion.example.com
    User admin
    IdentityFile ~/.ssh/bastion_ed25519

使用上述配置时，"host": "prod" 无需额外参数即可使用。

安全注意事项

• 命令将在远程系统上以 SSH 用户的权限执行——请确保远程端设置了适当的访问控制。
• 默认设置 BatchMode=yes，以防止 ssh 进程因交互式提示而挂起。
• 主机和用户名输入会经过验证，以防止 SSH 选项注入。
• 命令输出可能包含敏感数据；请妥善处理。

许可证

MIT