classfang/ssh-mcp-server

基于 SSH 的 MCP (Model Context Protocol) 服务器，允许通过 MCP 协议远程执行 SSH 命令。
English Document | 中文文档
📝 项目介绍
ssh-mcp-server 是一个桥接工具，可以让 AI 助手等支持 MCP 协议的应用通过标准化接口执行远程 SSH 命令。这使得 AI 助手能够安全地操作远程服务器，执行命令并获取结果，而无需直接暴露 SSH 凭据给 AI 模型。
💬 如有任何问题，欢迎加入微信群交流：
✨ 功能亮点
- **🔒 安全连接**：支持多种安全的 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
NPM: 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. 🔑 账号密码（最简单）
2. 🔐 账号 + 私钥
3. 🔏 带密码的私钥
4. 📋 复用 ~/.ssh/config
如果你已经在 ~/.ssh/config 配置了主机别名，服务器会自动从中读取连接参数，mcp.json 里就不用再写一遍。
假设你的 ~/.ssh/config 包含：
你也可以指定自定义的 SSH 配置文件路径：
**注意**：命令行参数优先级高于 SSH 配置值。例如，如果你指定了 --port 2222，它会覆盖 SSH 配置中的端口。
需要一次连接多台已在 SSH config 中配好的主机时，参见下文「10. 多 SSH 连接配置」的方式四。
5. 🌐 通过代理连接
当目标主机只能通过代理访问时，可使用 --proxy 配置 SOCKS5、HTTP 或 HTTPS 代理。
支持的 URL 格式：
HTTP 和 HTTPS 代理通过 CONNECT 方法建立到 SSH 服务的隧道，用户名和密码使用 Basic 代理认证。HTTP、HTTPS 未填写端口时分别默认使用 80、443；SOCKS5 必须填写端口。HTTPS 代理证书使用 Node.js 默认信任链进行验证。
原有 socksProxy 配置和 --socksProxy 参数继续兼容，但只接受 socks:// 和 socks5://。不要同时配置 proxy 和 socksProxy。
6. 📝 使用命令白名单 / 黑名单
通过 --whitelist 和 --blacklist 限制服务器允许执行的命令范围。多个模式之间用逗号分隔，每个模式都是一个正则表达式。**生产环境强烈建议配置**。白名单按完整命令匹配；启用白名单时，包含 ;、&、|、反引号、$()、>、 注意：黑名单正则默认区分大小写，^shutdown.* 拦不住 Shutdown /a。上面的示例使用 [sS] 等字符组兼容不同 Node.js 版本，无需作用域内联标志 (?i:模式)。旧版 Node.js 可能不支持该内联语法，裸 (?i) 也不受 JavaScript 正则支持；非法正则会让服务器启动失败。JSON 字符串中的反斜杠需要转义：正则的 \s 在 JSON 中写作 \\s，用于容忍命令前的空白。
>
> 注意：如果同时指定了白名单和黑名单，系统会先检查命令是否完整匹配白名单，再检查是否命中黑名单，命令必须同时通过两项检查才能被执行。建议在白名单正则中始终显式使用 ^ 和 $，便于阅读和审计。需要组合执行多个操作时，请将逻辑放入经过单独审查的脚本，并只允许固定的脚本调用；不要依赖字符串切割来解析 Shell 语法。
7. 🧩 使用命令模板包裹命令
commandTemplate 会把每条执行的命令套进一个模板里，适合切换用户（su）、放进容器、或经过跳板机的场景。当命令会作为 shell 参数传入时使用 ，需要原样插入时使用 ；模板会**在目录 cd 拼接之后**应用，因此整个 cd ... && 都会被包裹起来。
当指定目录为 /data 执行 ls /app 时，实际发送的命令是：
其他常见模板：
8. 🚇 堡垒机 / 跳板机（transportMode: shell）
transportMode 默认是 exec。出现下面这些情况时，应该切换到 shell：
- SSH 登录成功，但 exec 执行命令失败
- 远端必须等登录 banner、profile、环境初始化完成后才能正常执行命令
- 连接目标本质上是堡垒机或只暴露交互式 shell 的设备
两者差异：
- exec：支持 execute-command、upload、download
- shell：命令通过持久 shell 会话串行执行，内部带命令队列；但**不支持** upload / download，因为该模式下禁用了 SFTP
JSON 配置文件中还可以通过 shellCommandTimeoutMs 覆盖 shell 模式下单条命令的默认超时。
9. 🔐 多因素认证（2FA / MFA）
当 SSH 服务器要求多因素认证（密码 + 私钥 + 2FA 验证码）时启用 tryKeyboard。密码和私钥会自动提供；对于非密码提示，请在连接前通过服务端环境变量 SSH_MCP_2FA_CODE 提供验证码。