\n\n
![\"ssh-mcp-server](\"images/ssh-mcp-server-logo-v2.png\")
\n\n# ssh-mcp-server\n\n\n\n\n\n\n\n\n\n基于 SSH 的 MCP (Model Context Protocol) 服务器，允许通过 MCP 协议远程执行 SSH 命令。\n\n[English Document](README_EN.md) | 中文文档\n\n
![\"wechat\"](\"images/wechat.jpg\")
\n\n## ✨ 功能亮点\n\n- **🔒 安全连接**：支持多种安全的 SSH 连接方式，包括密码认证和私钥认证（支持带密码的私钥）\n- **🛡️ 命令安全控制**：通过灵活的黑白名单机制，精确控制允许执行的命令范围，防止危险操作\n- **🔄 标准化接口**：符合 MCP 协议规范，与支持该协议的 AI 助手无缝集成\n- **🚇 双传输模式**：同时支持 `exec` 和 `shell` 两种 transport，兼容直连主机与堡垒机或跳板机场景\n- **🌐 HTTP 接入**：默认使用 stdio；加上 `--mcp-transport http` 后通过 Streamable HTTP 提供 MCP 端点\n- **📂 文件传输**：支持双向文件传输功能，可上传本地文件到服务器或从服务器下载文件\n- **🔑 凭据隔离**：SSH 凭据完全在本地管理，不会暴露给 AI 模型，增强安全性\n- **🚀 即用即走**：使用 NPX 可直接运行，无需全局安装，方便快捷\n\n## 📦 开源仓库\n\nGitHub：[https://github.com/classfang/ssh-mcp-server](https://github.com/classfang/ssh-mcp-server)\n\nNPM: [https://www.npmjs.com/package/@fangjunjie/ssh-mcp-server](https://www.npmjs.com/package/@fangjunjie/ssh-mcp-server)\n\n## 🛠️ 工具列表\n\n| 工具 | 名称 | 描述 |\n|---------|-----------|----------|\n| execute-command | 命令执行工具 | 在远程服务器上执行 SSH 命令并获取执行结果 |\n| upload | 文件上传工具 | 将本地文件或整个目录上传到远程服务器指定位置 |\n| download | 文件下载工具 | 从远程服务器下载文件或整个目录到本地指定位置 |\n| read-file | 读文件工具 | 通过 SFTP 读取远程文本文件，可按字节偏移分页，拒绝二进制文件 |\n| write-file | 写文件工具 | 通过 SFTP 直接写入文本内容（覆盖或追加），不经过 shell 引号转义 |\n| list-servers | 服务器列表工具 | 列出所有可用SSH服务器配置 |\n| job-start / job-status / job-kill / job-list | 后台任务工具 | 启动超过命令超时限制的长任务，轮询输出与退出码，终止任务 |\n\n## 📚 使用方法\n\n### 0. 🤖 通过 AI Skill 快速配置（推荐）\n\n如果你使用支持 skill 的 AI 编程助手（如 Claude Code），可以直接使用内置的 **ssh-mcp-helper** skill 通过交互式问答完成安装和配置，无需手动编辑 JSON 文件。\n\n**使用方式：**\n\n1. 从本仓库 `skills/` 目录安装该 skill\n2. 告诉你的 AI 助手：\"帮我配置 ssh-mcp-server\" 或 \"给 Cursor 加一个 SSH MCP 连接\"\n3. skill 会逐步引导你：检查 Node.js 环境 → 选择 MCP 客户端 → 选择认证方式 → 收集连接参数 → 生成并写入配置\n\n该 skill 支持下文所有场景（账号密码、私钥、SSH config 复用、SOCKS 代理、堡垒机、多连接、2FA、命令限制等），并自动生成格式正确的配置。\n\n---\n\n下面的章节按从简单到复杂的顺序排列，最简单的入门方式就是用账号密码连接服务器。直接复制对应场景下的 `mcp.json` 配置到你的 MCP 客户端即可使用。\n\n> **⚠️ 重要提示**：在 MCP 配置文件中，每个命令行参数和其值必须是 `args` 数组中的独立元素。不要用空格将它们连接在一起。例如，使用 `\"--host\", \"192.168.1.1\"` 而不是 `\"--host 192.168.1.1\"`。\n\n### 1. 🔑 账号密码（最简单）\n\n```json\n{\n \"mcpServers\": {\n \"ssh-mcp-server\": {\n \"command\": \"npx\",\n \"args\": [\n \"-y\",\n \"@fangjunjie/ssh-mcp-server\",\n \"--host\", \"192.168.1.1\",\n \"--port\", \"22\",\n \"--username\", \"root\",\n \"--password\", \"pwd123456\"\n ]\n }\n }\n}\n```\n\n### 2. 🔐 账号 + 私钥\n\n```json\n{\n \"mcpServers\": {\n \"ssh-mcp-server\": {\n \"command\": \"npx\",\n \"args\": [\n \"-y\",\n \"@fangjunjie/ssh-mcp-server\",\n \"--host\", \"192.168.1.1\",\n \"--port\", \"22\",\n \"--username\", \"root\",\n \"--privateKey\", \"~/.ssh/id_rsa\"\n ]\n }\n }\n}\n```\n\n### 3. 🔏 带密码的私钥\n\n```json\n{\n \"mcpServers\": {\n \"ssh-mcp-server\": {\n \"command\": \"npx\",\n \"args\": [\n \"-y\",\n \"@fangjunjie/ssh-mcp-server\",\n \"--host\", \"192.168.1.1\",\n \"--port\", \"22\",\n \"--username\", \"root\",\n \"--privateKey\", \"~/.ssh/id_rsa\",\n \"--passphrase\", \"pwd123456\"\n ]\n }\n }\n}\n```\n\n### 4. 📋 复用 `~/.ssh/config`\n\n如果你已经在 `~/.ssh/config` 配置了主机别名，服务器会自动从中读取连接参数，`mcp.json` 里就不用再写一遍。\n\n```json\n{\n \"mcpServers\": {\n \"ssh-mcp-server\": {\n \"command\": \"npx\",\n \"args\": [\n \"-y\",\n \"@fangjunjie/ssh-mcp-server\",\n \"--host\", \"myserver\"\n ]\n }\n }\n}\n```\n\n假设你的 `~/.ssh/config` 包含：\n\n```\nHost myserver\n HostName 192.168.1.1\n Port 22\n User root\n IdentityFile ~/.ssh/id_rsa\n```\n\n你也可以指定自定义的 SSH 配置文件路径：\n\n```json\n{\n \"mcpServers\": {\n \"ssh-mcp-server\": {\n \"command\": \"npx\",\n \"args\": [\n \"-y\",\n \"@fangjunjie/ssh-mcp-server\",\n \"--host\", \"myserver\",\n \"--ssh-config-file\", \"/path/to/custom/ssh_config\"\n ]\n }\n }\n}\n```\n\n**注意**：命令行参数优先级高于 SSH 配置值。例如，如果你指定了 `--port 2222`，它会覆盖 SSH 配置中的端口。\n\n需要一次连接多台已在 SSH config 中配好的主机时，参见下文「10. 多 SSH 连接配置」的方式四。\n\n### 5. 🌐 通过代理连接\n\n当目标主机只能通过代理访问时，可使用 `--proxy` 配置 SOCKS5、HTTP 或 HTTPS 代理。\n\n```json\n{\n \"mcpServers\": {\n \"ssh-mcp-server\": {\n \"command\": \"npx\",\n \"args\": [\n \"-y\",\n \"@fangjunjie/ssh-mcp-server\",\n \"--host\", \"192.168.1.1\",\n \"--port\", \"22\",\n \"--username\", \"root\",\n \"--password\", \"pwd123456\",\n \"--proxy\", \"http://username:password@proxy-host:proxy-port\"\n ]\n }\n }\n}\n```\n\n支持的 URL 格式：\n\n```text\nsocks://username:password@proxy-host:1080\nsocks5://username:password@proxy-host:1080\nhttp://username:password@proxy-host:8080\nhttps://username:password@proxy-host:8443\n```\n\nHTTP 和 HTTPS 代理通过 `CONNECT` 方法建立到 SSH 服务的隧道，用户名和密码使用 Basic 代理认证。HTTP、HTTPS 未填写端口时分别默认使用 `80`、`443`；SOCKS5 必须填写端口。HTTPS 代理证书使用 Node.js 默认信任链进行验证。\n\n原有 `socksProxy` 配置和 `--socksProxy` 参数继续兼容，但只接受 `socks://` 和 `socks5://`。不要同时配置 `proxy` 和 `socksProxy`。\n\n### 6. 📝 使用命令白名单 / 黑名单\n\n通过 `--whitelist` 和 `--blacklist` 限制服务器允许执行的命令范围。多个模式之间用逗号分隔，每个模式都是一个正则表达式。**生产环境强烈建议配置**。白名单按完整命令匹配；启用白名单时，包含 `;`、`&`、`|`、反引号、`$()`、`>`、`<` 或换行符的命令会被直接拒绝，不能使用命令连接、管道、重定向或命令替换绕过校验。\n\n白名单示例（仅允许只读型查看命令）：\n\n```json\n{\n \"mcpServers\": {\n \"ssh-mcp-server\": {\n \"command\": \"npx\",\n \"args\": [\n \"-y\",\n \"@fangjunjie/ssh-mcp-server\",\n \"--host\", \"192.168.1.1\",\n \"--port\", \"22\",\n \"--username\", \"root\",\n \"--password\", \"pwd123456\",\n \"--whitelist\", \"^ls(?: [A-Za-z0-9_./-]+)*$,^cat [A-Za-z0-9_./-]+$,^df(?: -[A-Za-z]+)*(?: [A-Za-z0-9_./-]+)?$\"\n ]\n }\n }\n}\n```\n\n黑名单示例（屏蔽危险命令）：\n\n```json\n{\n \"mcpServers\": {\n \"ssh-mcp-server\": {\n \"command\": \"npx\",\n \"args\": [\n \"-y\",\n \"@fangjunjie/ssh-mcp-server\",\n \"--host\", \"192.168.1.1\",\n \"--port\", \"22\",\n \"--username\", \"root\",\n \"--password\", \"pwd123456\",\n \"--blacklist\", \"^\\\\s*[rR][mM] .*,^\\\\s*[sS][hH][uU][tT][dD][oO][wW][nN].*,^\\\\s*[rR][eE][bB][oO][oO][tT].*\"\n ]\n }\n }\n}\n```\n\n> 注意：黑名单正则默认区分大小写，`^shutdown.*` 拦不住 `Shutdown /a`。上面的示例使用 `[sS]` 等字符组兼容不同 Node.js 版本，无需作用域内联标志 `(?i:模式)`。旧版 Node.js 可能不支持该内联语法，裸 `(?i)` 也不受 JavaScript 正则支持；非法正则会让服务器启动失败。JSON 字符串中的反斜杠需要转义：正则的 `\\s` 在 JSON 中写作 `\\\\s`，用于容忍命令前的空白。\n>\n> 注意：如果同时指定了白名单和黑名单，系统会先检查命令是否完整匹配白名单，再检查是否命中黑名单，命令必须同时通过两项检查才能被执行。建议在白名单正则中始终显式使用 `^` 和 `$`，便于阅读和审计。需要组合执行多个操作时，请将逻辑放入经过单独审查的脚本，并只允许固定的脚本调用；不要依赖字符串切割来解析 Shell 语法。\n\n### 7. 🧩 使用命令模板包裹命令\n\n`commandTemplate` 会把每条执行的命令套进一个模板里，适合切换用户（`su`）、放进容器、或经过跳板机的场景。当命令会作为 shell 参数传入时使用 `