@lynmoe/ssh-mcp

通过 stdio 暴露 MCP 工具，使用本机 OpenSSH（ControlMaster）在远程主机上执行 shell：命令经 stdin 传给远端 shell -s（默认 bash），无 TTY。

环境要求

• Node.js ≥ 18
• 已安装并可用的 ssh（Windows 需 OpenSSH 客户端）

安装

从 npm 安装：

npm install @lynmoe/ssh-mcp

本地开发时在仓库根目录执行：

npm install
npm run build

开发调试（不编译）：

npm run dev

使用方式

由 MCP 宿主（如 Cursor）在子进程中启动本服务后，通过协议调用 list_hosts / run_on_host。若需命令行试调，可使用 mcporter 等 CLI 对已写入 mcporter.json 的 stdio 服务发起 call。

在 MCP 客户端中配置

使用 stdio 启动服务。已安装 npm 包时可用 npx（推荐），或指向包内 dist/index.js：

{
  "mcpServers": {
    "ssh-mcp": {
      "command": "npx",
      "args": ["-y", "@lynmoe/ssh-mcp"]
    }
  }
}

本地克隆开发时可将 args 改为 ["/你的路径/ssh-mcp/dist/index.js"] 并用 "command": "node"。

在 Cursor 中可将上述片段合并进 MCP 设置；其他支持 MCP 的 IDE 同理。

工具说明

| 工具 | 作用 | | ------------- | -------------------------------------------------------------------------------------------------------- | | list_hosts | 从 ~/.ssh/config 及 Include 中列出 Host 别名（不发起连接）。 | | run_on_host | 在指定目标上执行脚本：host、command、timeoutMs（单次执行上限 ms）、可选 shell（仅裸名，默认 bash）。同一目标复用一条 SSH 连接；空闲一段时间后关闭主连接。 |

环境变量（可选）

| 变量 | 含义 | | ------------------ | -------------------------------------------------- | | SSH_CONFIG | 自定义 ssh 配置文件路径（否则使用 ~/.ssh/config）。 | | SSH_MCP_SSH_PATH | 指定 ssh 可执行文件路径。 | | SSH_MCP_IDLE_MS | 连接池空闲断开时间（毫秒），默认 120000，有效范围约 1000–86400000。 | | SSH_MCP_CONTROL_DIR | ControlMaster 套接字所在目录。POSIX 默认 /tmp（避免 macOS 上 TMPDIR 过长导致 path too long for Unix domain socket）；可设为更短路径。 |

命令行直接运行

全局或项目内安装后：

ssh-mcp

或：

node dist/index.js

进程从 stdin/stdout 读写 MCP 消息，请勿向 stdout 打印其它内容。

开源协议

MIT

安全提示

本服务等价于在运行它的用户身份下执行 ssh；仅在信任的 MCP 宿主与网络环境中启用，并确保 ~/.ssh 与密钥权限得当。