# @fangjunjie/ssh-mcp-server 中文文档 规范地址：https://npmcn.com/package/%40fangjunjie/ssh-mcp-server/ 版本：1\.11\.0 npm 元数据更新时间：2026-11-04T06:29:46.060Z 中文译文更新时间：2026-11-14T09:51:22.684Z 软件包许可：ISC 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40fangjunjie/ssh-mcp-server 原文对照：https://npmcn.com/package/%40fangjunjie/ssh-mcp-server/?lang=original 项目主页：https://github.com/classfang/ssh-mcp-server#readme 源码仓库：https://github.com/classfang/ssh-mcp-server ## 关键信息（来自 npm 元数据） - 包体积（解压后）：212 kB，25 个文件 - 模块格式：ES Module - TypeScript 类型：未声明 - 运行依赖：4 个 - 首次发布：2025-04-16T08:18:18.645Z - 最新版本发布：2026-11-04T06:29:45.838Z - 近 30 天下载量：9326（2026-10-15 至 2026-11-13，npm 官方下载统计） - 已发布版本数：39（近 12 个月 25 个） ## 中文简介 基于 SSH 的 MCP 服务器 (Hi SSH CHL MCP → ) ## 安装 ```sh npm install @fangjunjie/ssh-mcp-server ``` 也可以使用：`pnpm add @fangjunjie/ssh-mcp-server`、`yarn add @fangjunjie/ssh-mcp-server`、`bun add @fangjunjie/ssh-mcp-server` ## README ![ssh-mcp-server logo](https://npmcn.com/package/%40fangjunjie/ssh-mcp-server/images/ssh-mcp-server-logo-v2.png) # ssh-mcp-server ![NPM Version](https://img.shields.io/npm/v/%40fangjunjie%2Fssh-mcp-server?label=%40fangjunjie%2Fssh-mcp-server) ![GitHub forks](https://img.shields.io/github/forks/classfang/ssh-mcp-server) ![GitHub Repo stars](https://img.shields.io/github/stars/classfang/ssh-mcp-server) ![GitHub Issues or Pull Requests](https://img.shields.io/github/issues/classfang/ssh-mcp-server) ![GitHub Issues or Pull Requests](https://img.shields.io/github/issues-closed/classfang/ssh-mcp-server) ![GitHub Issues or Pull Requests](https://img.shields.io/github/issues-pr/classfang/ssh-mcp-server) ![GitHub Issues or Pull Requests](https://img.shields.io/github/issues-pr-closed/classfang/ssh-mcp-server) 基于 SSH 的 MCP (Model Context Protocol) 服务器，允许通过 MCP 协议远程执行 SSH 命令。 [English Document](https://npmcn.com/package/%40fangjunjie/ssh-mcp-server/README_EN.md) | 中文文档 ## 📝 项目介绍 ssh-mcp-server 是一个桥接工具，可以让 AI 助手等支持 MCP 协议的应用通过标准化接口执行远程 SSH 命令。这使得 AI 助手能够安全地操作远程服务器，执行命令并获取结果，而无需直接暴露 SSH 凭据给 AI 模型。 💬 如有任何问题，欢迎加入微信群交流： ![wechat](https://npmcn.com/package/%40fangjunjie/ssh-mcp-server/images/wechat.jpg) ## ✨ 功能亮点 - **🔒 安全连接**：支持多种安全的 SSH 连接方式，包括密码认证和私钥认证（支持带密码的私钥） - **🛡️ 命令安全控制**：通过灵活的黑白名单机制，精确控制允许执行的命令范围，防止危险操作 - **🔄 标准化接口**：符合 MCP 协议规范，与支持该协议的 AI 助手无缝集成 - **🚇 双传输模式**：同时支持 `exec` 和 `shell` 两种 transport，兼容直连主机与堡垒机或跳板机场景 - **🌐 HTTP 接入**：默认使用 stdio；加上 `--mcp-transport http` 后通过 Streamable HTTP 提供 MCP 端点 - **📂 文件传输**：支持双向文件传输功能，可上传本地文件到服务器或从服务器下载文件 - **🔑 凭据隔离**：SSH 凭据完全在本地管理，不会暴露给 AI 模型，增强安全性 - **🚀 即用即走**：使用 NPX 可直接运行，无需全局安装，方便快捷 ## 📦 开源仓库 GitHub：[https://github.com/classfang/ssh-mcp-server](https://github.com/classfang/ssh-mcp-server) NPM: [https://www.npmjs.com/package/@fangjunjie/ssh-mcp-server](https://www.npmjs.com/package/@fangjunjie/ssh-mcp-server) ## 🛠️ 工具列表 | 工具 | 名称 | 描述 | | --- | --- | --- | | execute-command | 命令执行工具 | 在远程服务器上执行 SSH 命令并获取执行结果 | | upload | 文件上传工具 | 将本地文件或整个目录上传到远程服务器指定位置 | | download | 文件下载工具 | 从远程服务器下载文件或整个目录到本地指定位置 | | read-file | 读文件工具 | 通过 SFTP 读取远程文本文件，可按字节偏移分页，拒绝二进制文件 | | write-file | 写文件工具 | 通过 SFTP 直接写入文本内容（覆盖或追加），不经过 shell 引号转义 | | list-servers | 服务器列表工具 | 列出所有可用SSH服务器配置 | | job-start / job-status / job-kill / job-list | 后台任务工具 | 启动超过命令超时限制的长任务，轮询输出与退出码，终止任务 | ## 📚 使用方法 ### 0\. 🤖 通过 AI Skill 快速配置（推荐） 如果你使用支持 skill 的 AI 编程助手（如 Claude Code），可以直接使用内置的 **ssh-mcp-helper** skill 通过交互式问答完成安装和配置，无需手动编辑 JSON 文件。 **使用方式：** 1. 从本仓库 `skills/` 目录安装该 skill 2. 告诉你的 AI 助手："帮我配置 ssh-mcp-server" 或 "给 Cursor 加一个 SSH MCP 连接" 3. skill 会逐步引导你：检查 Node.js 环境 → 选择 MCP 客户端 → 选择认证方式 → 收集连接参数 → 生成并写入配置 该 skill 支持下文所有场景（账号密码、私钥、SSH config 复用、SOCKS 代理、堡垒机、多连接、2FA、命令限制等），并自动生成格式正确的配置。 * * * 下面的章节按从简单到复杂的顺序排列，最简单的入门方式就是用账号密码连接服务器。直接复制对应场景下的 `mcp.json` 配置到你的 MCP 客户端即可使用。 > **⚠️ 重要提示**：在 MCP 配置文件中，每个命令行参数和其值必须是 `args` 数组中的独立元素。不要用空格将它们连接在一起。例如，使用 `"--host", "192.168.1.1"` 而不是 `"--host 192.168.1.1"`。 ### 1\. 🔑 账号密码（最简单） ```json { "mcpServers": { "ssh-mcp-server": { "command": "npx", "args": [ "-y", "@fangjunjie/ssh-mcp-server", "--host", "192.168.1.1", "--port", "22", "--username", "root", "--password", "pwd123456" ] } } } ``` ### 2\. 🔐 账号 + 私钥 ```json { "mcpServers": { "ssh-mcp-server": { "command": "npx", "args": [ "-y", "@fangjunjie/ssh-mcp-server", "--host", "192.168.1.1", "--port", "22", "--username", "root", "--privateKey", "~/.ssh/id_rsa" ] } } } ``` ### 3\. 🔏 带密码的私钥 ```json { "mcpServers": { "ssh-mcp-server": { "command": "npx", "args": [ "-y", "@fangjunjie/ssh-mcp-server", "--host", "192.168.1.1", "--port", "22", "--username", "root", "--privateKey", "~/.ssh/id_rsa", "--passphrase", "pwd123456" ] } } } ``` ### 4\. 📋 复用 `~/.ssh/config` 如果你已经在 `~/.ssh/config` 配置了主机别名，服务器会自动从中读取连接参数，`mcp.json` 里就不用再写一遍。 ```json { "mcpServers": { "ssh-mcp-server": { "command": "npx", "args": [ "-y", "@fangjunjie/ssh-mcp-server", "--host", "myserver" ] } } } ``` 假设你的 `~/.ssh/config` 包含： ``` Host myserver HostName 192.168.1.1 Port 22 User root IdentityFile ~/.ssh/id_rsa ``` 你也可以指定自定义的 SSH 配置文件路径： ```json { "mcpServers": { "ssh-mcp-server": { "command": "npx", "args": [ "-y", "@fangjunjie/ssh-mcp-server", "--host", "myserver", "--ssh-config-file", "/path/to/custom/ssh_config" ] } } } ``` **注意**：命令行参数优先级高于 SSH 配置值。例如，如果你指定了 `--port 2222`，它会覆盖 SSH 配置中的端口。 需要一次连接多台已在 SSH config 中配好的主机时，参见下文「10. 多 SSH 连接配置」的方式四。 ### 5\. 🌐 通过代理连接 当目标主机只能通过代理访问时，可使用 `--proxy` 配置 SOCKS5、HTTP 或 HTTPS 代理。 ```json { "mcpServers": { "ssh-mcp-server": { "command": "npx", "args": [ "-y", "@fangjunjie/ssh-mcp-server", "--host", "192.168.1.1", "--port", "22", "--username", "root", "--password", "pwd123456", "--proxy", "http://username:password@proxy-host:proxy-port" ] } } } ``` 支持的 URL 格式： ```text socks://username:password@proxy-host:1080 socks5://username:password@proxy-host:1080 http://username:password@proxy-host:8080 https://username:password@proxy-host:8443 ``` HTTP 和 HTTPS 代理通过 `CONNECT` 方法建立到 SSH 服务的隧道，用户名和密码使用 Basic 代理认证。HTTP、HTTPS 未填写端口时分别默认使用 `80`、`443`；SOCKS5 必须填写端口。HTTPS 代理证书使用 Node.js 默认信任链进行验证。 原有 `socksProxy` 配置和 `--socksProxy` 参数继续兼容，但只接受 `socks://` 和 `socks5://`。不要同时配置 `proxy` 和 `socksProxy`。 ### 6\. 📝 使用命令白名单 / 黑名单 通过 `--whitelist` 和 `--blacklist` 限制服务器允许执行的命令范围。多个模式之间用逗号分隔，每个模式都是一个正则表达式。**生产环境强烈建议配置**。白名单按完整命令匹配；启用白名单时，包含 `;`、`&`、`|`、反引号、`$()`、`>`、`<` 或换行符的命令会被直接拒绝，不能使用命令连接、管道、重定向或命令替换绕过校验。 白名单示例（仅允许只读型查看命令）： ```json { "mcpServers": { "ssh-mcp-server": { "command": "npx", "args": [ "-y", "@fangjunjie/ssh-mcp-server", "--host", "192.168.1.1", "--port", "22", "--username", "root", "--password", "pwd123456", "--whitelist", "^ls(?: [A-Za-z0-9_./-]+)*$,^cat [A-Za-z0-9_./-]+$,^df(?: -[A-Za-z]+)*(?: [A-Za-z0-9_./-]+)?$" ] } } } ``` 黑名单示例（屏蔽危险命令）： ```json { "mcpServers": { "ssh-mcp-server": { "command": "npx", "args": [ "-y", "@fangjunjie/ssh-mcp-server", "--host", "192.168.1.1", "--port", "22", "--username", "root", "--password", "pwd123456", "--blacklist", "^\\s*[rR][mM] .*,^\\s*[sS][hH][uU][tT][dD][oO][wW][nN].*,^\\s*[rR][eE][bB][oO][oO][tT].*" ] } } } ``` > 注意：黑名单正则默认区分大小写，`^shutdown.*` 拦不住 `Shutdown /a`。上面的示例使用 `[sS]` 等字符组兼容不同 Node.js 版本，无需作用域内联标志 `(?i:模式)`。旧版 Node.js 可能不支持该内联语法，裸 `(?i)` 也不受 JavaScript 正则支持；非法正则会让服务器启动失败。JSON 字符串中的反斜杠需要转义：正则的 `\s` 在 JSON 中写作 `\\s`，用于容忍命令前的空白。 > > 注意：如果同时指定了白名单和黑名单，系统会先检查命令是否完整匹配白名单，再检查是否命中黑名单，命令必须同时通过两项检查才能被执行。建议在白名单正则中始终显式使用 `^` 和 `$`，便于阅读和审计。需要组合执行多个操作时，请将逻辑放入经过单独审查的脚本，并只允许固定的脚本调用；不要依赖字符串切割来解析 Shell 语法。 ### 7\. 🧩 使用命令模板包裹命令 `commandTemplate` 会把每条执行的命令套进一个模板里，适合切换用户（`su`）、放进容器、或经过跳板机的场景。当命令会作为 shell 参数传入时使用 ``，需要原样插入时使用 ``；模板会**在目录 `cd` 拼接之后**应用，因此整个 `cd ... && <实际命令>` 都会被包裹起来。 ```json { "mcpServers": { "ssh-mcp-server": { "command": "npx", "args": [ "-y", "@fangjunjie/ssh-mcp-server", "--host", "10.0.0.1", "--port", "22", "--username", "deploy", "--password", "xxx", "--command-template", "su root -c " ] } } } ``` 当指定目录为 `/data` 执行 `ls /app` 时，实际发送的命令是： ``` su root -c 'cd -- '\''/data'\'' && ls /app' ``` 其他常见模板： ```text sudo bash -c docker exec -i mycontainer sh -c ssh jumphost ``` ### 8\. 🚇 堡垒机 / 跳板机（`transportMode: shell`） `transportMode` 默认是 `exec`。出现下面这些情况时，应该切换到 `shell`： - SSH 登录成功，但 `exec` 执行命令失败 - 远端必须等登录 banner、profile、环境初始化完成后才能正常执行命令 - 连接目标本质上是堡垒机或只暴露交互式 shell 的设备 两者差异： - `exec`：支持 `execute-command`、`upload`、`download` - `shell`：命令通过持久 shell 会话串行执行，内部带命令队列；但**不支持** `upload` / `download`，因为该模式下禁用了 SFTP ```json { "mcpServers": { "ssh-mcp-server": { "command": "npx", "args": [ "-y", "@fangjunjie/ssh-mcp-server", "--host", "bastion.example.com", "--port", "22", "--username", "ops", "--password", "pwd123456", "--transport-mode", "shell", "--shell-ready-timeout", "15000" ] } } } ``` JSON 配置文件中还可以通过 `shellCommandTimeoutMs` 覆盖 shell 模式下单条命令的默认超时。 ### 9\. 🔐 多因素认证（2FA / MFA） 当 SSH 服务器要求多因素认证（密码 + 私钥 + 2FA 验证码）时启用 `tryKeyboard`。密码和私钥会自动提供；对于非密码提示，请在连接前通过服务端环境变量 `SSH_MCP_2FA_CODE` 提供验证码。 ```json { "mcpServers": { "ssh-mcp-server": { "command": "npx", "args": [ "-y", "@fangjunjie/ssh-mcp-server", "--host", "example.com", "--port", "22", "--username", "user", "--password", "your_password", "--privateKey", "/path/to/key", "--try-keyboard" ] } } } ``` **认证流程：** 1. 私钥认证（如果提供） 2. 密码认证（如果提供） 3. 键盘交互式认证通过 `SSH_MCP_2FA_CODE` 提供 2FA 验证码 ### 10\. 🧩 多 SSH 连接配置 需要在同一个 MCP server 里同时管理多个 SSH 目标时，给每个连接命名，调用时通过 `connectionName` 选择。共有四种配置方式： #### 📄 方式一：使用配置文件（推荐） 创建 JSON 配置文件（例如 `ssh-config.json`）： **数组格式：** ```json [ { "name": "dev", "host": "1.2.3.4", "port": 22, "username": "alice", "password": "{abc=P100s0}", "socksProxy": "socks://127.0.0.1:10808", "commandTimeoutMs": 120000, "maxOutputBytes": 10485760 }, { "name": "bastion", "host": "9.9.9.9", "port": 22, "username": "ops", "password": "pwd123456", "transportMode": "shell", "shellReadyTimeoutMs": 15000, "shellCommandTimeoutMs": 45000, "connectionTimeoutMs": 30000, "keepaliveIntervalMs": 10000, "keepaliveCountMax": 3 }, { "name": "prod", "host": "5.6.7.8", "port": 22, "username": "bob", "password": "yyy", "socksProxy": "socks://127.0.0.1:10808" }, { "name": "secure-server", "host": "secure.example.com", "port": 22, "username": "admin", "password": "your_password", "privateKey": "/path/to/private/key", "tryKeyboard": true } ] ``` **对象格式：** ```json { "dev": { "host": "1.2.3.4", "port": 22, "username": "alice", "password": "{abc=P100s0}", "socksProxy": "socks://127.0.0.1:10808", "commandTimeoutMs": 120000, "maxOutputBytes": 10485760 }, "bastion": { "host": "9.9.9.9", "port": 22, "username": "ops", "password": "pwd123456", "transportMode": "shell", "shellReadyTimeoutMs": 15000, "shellCommandTimeoutMs": 45000 }, "prod": { "host": "5.6.7.8", "port": 22, "username": "bob", "password": "yyy", "socksProxy": "socks://127.0.0.1:10808" } } ``` 然后使用 `--config-file` 参数： ```json { "mcpServers": { "ssh-mcp-server": { "command": "npx", "args": [ "-y", "@fangjunjie/ssh-mcp-server", "--config-file", "ssh-config.json" ] } } } ``` #### 🔧 方式二：使用 JSON 格式的 --ssh 参数 可以直接传递 JSON 格式的配置字符串： ```json { "mcpServers": { "ssh-mcp-server": { "command": "npx", "args": [ "-y", "@fangjunjie/ssh-mcp-server", "--ssh", "{\"name\":\"dev\",\"host\":\"1.2.3.4\",\"port\":22,\"username\":\"alice\",\"password\":\"{abc=P100s0}\",\"socksProxy\":\"socks://127.0.0.1:10808\"}", "--ssh", "{\"name\":\"bastion\",\"host\":\"9.9.9.9\",\"port\":22,\"username\":\"ops\",\"password\":\"pwd123456\",\"transportMode\":\"shell\",\"shellReadyTimeoutMs\":15000}", "--ssh", "{\"name\":\"prod\",\"host\":\"5.6.7.8\",\"port\":22,\"username\":\"bob\",\"password\":\"yyy\",\"socksProxy\":\"socks://127.0.0.1:10808\"}" ] } } } ``` #### 📝 方式三：旧格式逗号分隔（向后兼容） 对于密码中不包含特殊字符的简单情况，仍可使用旧格式： ```bash npx @fangjunjie/ssh-mcp-server \ --ssh "name=dev,host=1.2.3.4,port=22,user=alice,password=xxx" \ --ssh "name=prod,host=5.6.7.8,port=22,user=bob,password=yyy" ``` > **⚠️ 注意**：旧格式在处理包含特殊字符（如 `=`、`,`、`{`、`}`）的密码时可能会有问题。如果密码包含特殊字符，请使用方式一或方式二。 #### 🔑 方式四：`--host` 逗号分隔多值（复用 `~/.ssh/config`） `--host` 支持逗号分隔多个主机，进入多连接模式：每个主机作为独立连接，连接名为主机值本身；单值 `--host` 行为不变（连接名仍为 `default`）。每个主机独立套用与单主机相同的合并规则——命中 SSH config 别名则展开 HostName/Port/User/IdentityFile，命令行参数逐字段覆盖。适合多台主机都已在 `~/.ssh/config` 中配好的场景，无需编写任何 JSON： ```json { "mcpServers": { "ssh-mcp-server": { "command": "npx", "args": [ "-y", "@fangjunjie/ssh-mcp-server", "--host", "myserver,anotherserver", "--pty", "false" ] } } } ``` 认证解析按是否提供 CLI 认证参数（`--password`/`--privateKey`/`--agent`）分两种模式： - **未提供**：每个别名独立从 SSH config 解析认证（该别名的 IdentityFile 优先，其次 `~/.ssh` 默认身份文件回退，最后 SSH agent） - **提供**：全部主机共享该 CLI 认证，SSH config 的 IdentityFile 不参与（别名与裸 IP 行为一致，仅地址展开不同）；`--passphrase` 作为密钥解密口令可共享 其余 CLI 策略参数（`--pty`、`--whitelist`、超时等）作为进程级默认值共享给全部主机，无需逐服务器重复。任一主机缺用户名或认证来源时，启动即报错并列出该主机。需要为不同主机配置不同的策略（端口、白名单、超时等）时，请使用方式一。 在MCP工具调用时，通过 `connectionName` 参数指定目标连接名称，未指定时使用默认连接。 示例（在prod连接上执行命令）： ```json { "tool": "execute-command", "params": { "cmdString": "ls -al", "connectionName": "prod" } } ``` 示例（带超时选项的命令执行）： ```json { "tool": "execute-command", "params": { "cmdString": "ping -c 10 127.0.0.1", "connectionName": "prod", "timeout": 5000 } } ``` ### ⏱️ 命令执行超时 `execute-command` 工具支持超时选项，防止命令无限期挂起： - **timeout**: 单次调用的命令执行超时时间（毫秒，可选）；传入时会覆盖连接配置，未传入时使用对应连接配置或其 30000ms 默认值 - 在 JSON 配置文件里为单个连接设置 `commandTimeoutMs`，可以改掉这个默认值，避免每次调用都手动传 `timeout`（`exec` 模式） - `shell` 模式对应的配置项是 `shellCommandTimeoutMs` - 调用参数里的 `timeout` 始终优先于上面两个配置项 - 连接默认启用 SSH keepalive（`keepaliveIntervalMs`: 10000，`keepaliveCountMax`: 3），并使用 `connectionTimeoutMs` 限制连接建立时间 - SFTP 打开和传输操作使用 `sftpTimeoutMs` 控制超时（默认 300000ms） - 错误响应现在包含稳定的 `code`、`message`、`retriable` 字段，便于上层 Agent 处理 - 命令正常执行但以非零退出码结束（如 `grep` 无匹配、`diff` 有差异）时，`execute-command` 直接返回命令输出并在末尾附上 `[exit code] N`，不再作为工具错误、也不再包成 JSON；超时、连接失败、校验失败等真正的错误仍按上一条返回 `code`/`message`/`retriable` 这对于像 `ping`、`tail -f` 或其他可能阻塞执行的长时间运行进程特别有用。 ### 📄 文件读写与目录传输 - `read-file`：读取远程文本文件的一个字节范围（`offset`/`length`，默认最多 65536 字节）。返回内容前有 `[bytes] 起-止 of 总大小` 头部，未读完时给出 `next offset`，便于分页。检测到二进制内容（NUL 字节或大量无效 UTF-8）时拒绝并提示改用 `download` - `write-file`：直接把文本内容写入远程文件（`append: true` 追加，`mode` 指定新建文件权限）。内容不经过 shell，因此引号、`$`、反引号、多行内容都不需要转义 - `upload` / `download` 的路径是目录时会递归传输：远端目录不存在则创建，符号链接等非普通文件会跳过，单次最多 2000 个文件（更大的目录请先打包）。文件逐个传输，路径校验与单文件相同 - 以上均使用 SFTP，受 `allowedLocalPaths` / `allowedRemotePaths` 限制，`shell` 模式下不可用 ### 📦 命令输出限制 会限制单条命令捕获的 `stdout` 和 `stderr` 总量，避免大文件或无限输出耗尽 MCP server 内存： - 在 JSON 连接配置中使用 `maxOutputBytes` 设置上限，默认值为 `10485760`（10 MiB） - `maxOutputBytes` 必须是非负整数；设置为 `0` 可禁用限制，但不建议对不受信任的命令禁用 - 输出超过限制时，远端命令会被中止，工具返回 `OUTPUT_LIMIT_EXCEEDED` 错误和已经捕获的截断输出，不会把中止的命令误报为成功 - 当 `pty` 为 `false` 时，成功命令写入 `stderr` 的警告或进度信息会保留在 `[stderr]` 区段中 - `exec` 与 `shell` 两种模式都会应用该限制。区别在于 `exec` 模式只关闭该命令的通道，而 `shell` 模式的通道由该连接上的所有命令共用、远端在中止后仍会继续写入，因此会断开连接（与 shell 模式命令超时的处理一致） ### 🧵 后台任务 `execute-command` 会在超时后放弃命令，构建、部署这类长任务应改用后台任务： - `job-start`：在远端后台启动命令并立即返回 `job_id`。命令与 `execute-command` 一样经过 `commandWhitelist` / `commandBlacklist` 校验 - `job-status`：返回状态（`running` / `exited` / `killed` / `lost`）、退出码、已运行时间和输出。不带 `offset` 时返回输出末尾（`tailBytes`，默认 8192）；带 `offset` 时从该字节继续读，返回里给出 `next offset`，重复轮询只会读到新增内容 - `job-kill`：先 `SIGTERM`，5 秒后仍未退出则 `SIGKILL`，并递归终止子进程 - `job-list`：列出最近的任务及状态 - 任务的状态（命令、输出、pid、退出码）保存在远端 `~/.ssh-mcp-jobs//`，因此 MCP 重启或 SSH 连接断开都不会丢失；已结束超过 7 天的任务目录会在下次 `job-start` 时清理 - `job-kill` 只会向命令行中带有该任务 id 的进程发信号，避免 pid 被复用后误杀无关进程；此时任务显示为 `lost` - 远端需要 POSIX `sh`，有 `setsid` 时任务独立成进程组；`shell`（堡垒机）模式同样可用 ### 🗂️ 列出所有SSH服务器 可以通过MCP工具 `list-servers` 获取所有可用的SSH服务器配置： 调用示例： ```json { "tool": "list-servers", "params": {} } ``` 返回示例： ```json [ { "name": "dev", "host": "1.2.3.4", "port": 22, "username": "alice" }, { "name": "prod", "host": "5.6.7.8", "port": 22, "username": "bob" } ] ``` ### 🌐 HTTP 传输（Streamable HTTP） 进程默认使用 stdio，现有 `command` / `args` 配置保持可用。需要客户端通过 URL 连接时，用 `--mcp-transport http` 把同一进程跑成 MCP Streamable HTTP 服务，端点默认是 `http://127.0.0.1:3000/mcp`。 先在本机启动服务。令牌放在环境变量里，避免出现在进程参数中： ```bash export SSH_MCP_HTTP_TOKEN='replace-with-a-long-random-token' npx -y @fangjunjie/ssh-mcp-server \ --mcp-transport http \ --http-host 127.0.0.1 \ --http-port 3000 \ --host 192.168.1.1 \ --port 22 \ --username root \ --privateKey ~/.ssh/id_rsa ``` MCP 客户端配置 URL： ```json { "mcpServers": { "ssh-mcp-server": { "url": "http://127.0.0.1:3000/mcp", "headers": { "Authorization": "Bearer replace-with-a-long-random-token" } } } } ``` `--http-token` 与 `SSH_MCP_HTTP_TOKEN` 同时设置时，以命令行参数为准。未设置令牌时只建议绑定 `127.0.0.1`。监听 `0.0.0.0` 或其他非本机地址时，任何能访问该端口的客户端都可以执行远程命令，启动日志会给出警告。 ### ⚙️ 命令行选项参考 ```text 选项: --config-file JSON 配置文件路径（推荐用于多服务器配置） --ssh-config-file SSH 配置文件路径（默认: ~/.ssh/config） --ssh SSH 连接配置（可以是 JSON 字符串或旧格式） -h, --host SSH 服务器主机地址或 SSH 配置中的别名（逗号分隔多值进入多连接模式） -p, --port SSH 服务器端口 -u, --username SSH 用户名 -w, --password SSH 密码 -k, --privateKey SSH 私钥文件路径 -P, --passphrase 私钥密码（如果有的话） -a, --agent SSH agent socket 路径 --try-keyboard 启用键盘交互式认证以支持 2FA/MFA（默认: false） -W, --whitelist 命令白名单，以逗号分隔的正则表达式 -B, --blacklist 命令黑名单，以逗号分隔的正则表达式 --proxy 代理地址，支持 SOCKS5、HTTP 和 HTTPS -s, --socksProxy 旧版 SOCKS5 代理地址（兼容参数） --allowed-local-paths upload/download 允许访问的额外本地路径，逗号分隔 --allowed-remote-paths SFTP upload/download 允许访问的远端路径（POSIX 绝对路径或 Windows 盘符绝对路径，如 /var/log 或 C:/Users），逗号分隔 --transport-mode SSH transport 模式: exec 或 shell（默认: exec） --shell-ready-timeout shell 就绪探测超时，单位毫秒（默认: 10000） --command-template 命令模板；shell 参数用 ，原样插入用 --pty 为命令执行分配伪终端（默认: true） --pre-connect 启动时预连接所有配置的 SSH 服务器 --mcp-transport MCP 客户端传输：stdio 或 http（默认: stdio） --http-host HTTP 监听地址（默认: 127.0.0.1） --http-port HTTP 监听端口（默认: 3000，0 表示由系统分配） --http-path HTTP 端点路径（默认: /mcp） --http-token HTTP Bearer 令牌；未传时读取环境变量 SSH_MCP_HTTP_TOKEN --version, -v 打印包版本 --help 打印帮助信息 ``` ## 🛡️ 安全注意事项 该服务器提供了在远程服务器上执行命令和传输文件的强大功能。为确保安全使用，请注意以下几点： - **命令白名单**：_强烈建议_ 使用 `--whitelist` 选项来限制可执行的命令集合。如果没有白名单，任何命令都可以在远程服务器上执行，这可能带来重大的安全风险。 - **私钥安全**：服务器会将 SSH 私钥读入内存。请确保运行 `ssh-mcp-server` 的机器是安全的。不要将服务器暴露给不受信任的网络。 - **HTTP 端点**：HTTP 模式默认只监听 `127.0.0.1`。对外网卡监听时请配置 `--http-token` 或 `SSH_MCP_HTTP_TOKEN`。令牌相当于远程命令执行的钥匙，使用长随机字符串，并优先放在环境变量中。 - **拒绝服务攻击 (DoS)**：服务器没有内置的速率限制。攻击者可能通过向服务器发送大量连接请求或大文件传输来发起 DoS 攻击。建议在具有速率限制功能的防火墙或反向代理后面运行服务器。 - **路径遍历**：服务器内置了对本地文件系统路径遍历攻击的保护。但是，仍然需要注意在 `upload` 和 `download` 命令中使用的路径。 - **本地传输范围**：默认仅允许访问当前工作目录。只有在明确可信时，才建议通过 `--allowed-local-paths` 或配置文件中的 `allowedLocalPaths` 放宽范围。 - **远端传输范围**：SFTP upload/download 接受 POSIX 绝对路径（如 `/var/log/app.log`）和 Windows 盘符绝对路径（如 `C:/Users/foo/bar.txt`，自动归一化为正斜杠）。未配置 `allowedRemotePaths`（或 `--allowed-remote-paths`）时，任意远端路径都允许，但启动时会打印警告。强烈建议显式配置 `allowedRemotePaths` 白名单，避免模型被 prompt 注入后读写 `~/.ssh/authorized_keys`、`/etc/sshd_config` 之类敏感文件。 ## 🌟 Star 历史 ## Star History [![Star History Chart](https://api.star-history.com/chart?repos=classfang/ssh-mcp-server&type=date&legend=top-left&sealed_token=ndORao73xOZgyX7IvlIIOynMoeEP5Ds9YAG-zOfMMBlNepLdP3e7T7k9K94X8TdvuxplN5DXLolbF9jFFsYDD-1V0V8HO6B3swaPOvJaonKeiFNdAuWsXg)](https://www.star-history.com/?type=date&legend=top-left&repos=classfang%2Fssh-mcp-server) ## 常见问题 ### @fangjunjie/ssh-mcp-server 是什么？ 基于 SSH 的 MCP 服务器 \(Hi SSH CHL MCP → \) ### 如何安装 @fangjunjie/ssh-mcp-server？ 在项目目录运行 npm install @fangjunjie/ssh-mcp-server，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 ssh-mcp-server，可以用 npx ssh-mcp-server 直接运行。 ### @fangjunjie/ssh-mcp-server 支持 TypeScript 吗？ 该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/fangjunjie\_\_ssh-mcp-server 是否存在。 ### @fangjunjie/ssh-mcp-server 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @fangjunjie/ssh-mcp-server 可以商用吗？ @fangjunjie/ssh-mcp-server 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @fangjunjie/ssh-mcp-server 的下载量有多少？ 根据 npm 官方下载统计，@fangjunjie/ssh-mcp-server 在 2026/10/15 – 2026/11/13 这 30 天内被下载 9,326 次，日均约 311 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @fangjunjie/ssh-mcp-server 还在维护吗？ 最新版本 1\.11\.0 发布于 2026/11/04（10 天前）；至今共发布 39 个版本，其中过去 12 个月发布了 25 个；首次发布于 2025/04/16。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。