ssh-mcp-server 是一个基于 SSH 的 MCP 服务器，可以让支持 MCP 协议的 AI 助手通过标准化接口远程执行 SSH 命令、传输文件。如果你同时维护开发机、测试机、生产机或多台堡垒机，不需要为每台主机单独起一个服务——一个 ssh-mcp-server 实例就能管理多台主机，通过「命名连接」区分目标，调用时再用connectionName参数指定。本文带你快速掌握多连接配置的 4 种方式，从最简单的写法到复用~/.ssh/config的高级玩法。

为什么一个服务器就能管多台主机？

单主机模式下，--host只写一个地址，连接名默认是default。而多连接模式下，每个连接都有独立的名称（如dev、prod），各自持有独立的 host、端口、认证方式和超时策略，由连接管理器统一维护（核心实现在 ssh-connection-manager.ts）。

配置好之后，可以先调用list-servers工具确认所有连接及其状态（实现在 list-servers.ts）：

[ { "name": "dev", "host": "1.2.3.4", "port": 22, "username": "alice" }, { "name": "prod", "host": "5.6.7.8", "port": 22, "username": "bob" } ]

方式一：JSON 配置文件（推荐的多主机配置方法）

这是官方推荐的方式：把多台主机的连接参数写进一个 JSON 文件（例如ssh-config.json），再用--config-file参数加载。连接支持对象格式（推荐，直观）和数组格式，每台主机一个条目：

{ "dev": { "host": "1.2.3.4", "port": 22, "username": "alice", "password": "xxx" }, "prod": { "host": "5.6.7.8", "port": 22, "username": "bob", "privateKey": "/path/to/private/key" } }

每个连接都可以独立配置transportMode、commandTimeoutMs、maxOutputBytes、socksProxy、tryKeyboard等高级字段，互不影响。MCP 客户端配置随之变得非常简洁：

{ "mcpServers": { "ssh-mcp-server": { "command": "npx", "args": [ "-y", "@fangjunjie/ssh-mcp-server", "--config-file", "/path/to/ssh-config.json" ] } } }

💡 注意：配置里每个参数和它的值必须是args数组中独立的两个元素，不要写成"--config-file /path/to/ssh-config.json"。

方式二：--ssh 参数直接传 JSON 配置

不想单独维护一个配置文件？可以重复使用--ssh参数，每次都传一段 JSON 配置字符串：

npx -y @fangjunjie/ssh-mcp-server \ --ssh '{"name":"dev","host":"1.2.3.4","port":22,"username":"alice","password":"xxx"}' \ --ssh '{"name":"prod","host":"5.6.7.8","port":22,"username":"bob","password":"yyy"}'

✅ 优点：配置集中写在 mcp.json 里，换机器不用同步额外的配置文件。 ✅ JSON 格式天然支持密码中的特殊字符（=、,、{等），比旧格式更可靠。

方式三：旧式逗号分隔格式（向后兼容）

早期版本使用key=value,key=value的逗号分隔写法，目前仍然兼容：

npx -y @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）

如果多台主机都已经写进了你本机的~/.ssh/config（SSH 别名），这是最省事的写法——--host支持逗号分隔多个别名，直接进入多连接模式，无需编写任何 JSON：

"args": [ "-y", "@fangjunjie/ssh-mcp-server", "--host", "myserver,anotherserver" ]

• 连接名就是主机值本身（myserver、anotherserver），别名会被自动展开为 HostName/Port/User/IdentityFile（解析逻辑见 ssh-config-parser.ts）
• 如果不额外提供--password/--privateKey等认证参数，每个别名独立从 SSH config 解析认证信息，互不干扰
• --pty、--whitelist、超时等策略参数作为进程级默认值，共享给全部主机

适合「SSH config 里配好了一切，MCP 这边零 JSON」的场景。

4 种方式怎么选？一张表看懂

用 connectionName 指定目标主机

配置完成后，所有 MCP 工具（execute-command、upload、download、read-file等，参数定义可参考 execute-command.ts）都支持connectionName参数来路由到指定连接，不指定时走默认连接：

{ "tool": "execute-command", "params": { "cmdString": "uptime", "connectionName": "prod" } }

让 AI 助手「在 prod 上看下磁盘空间」「把文件上传到 dev」这类指令，就能精确落到对应主机上。

安全与实践建议

• 🛡️建议配置命令白名单：多主机尤其生产机，建议用--whitelist限制可执行命令范围
• 🔑凭据留在本地：私钥只填文件路径、密码只存在本地配置文件中，ssh-mcp-server 不会把凭据暴露给 AI 模型
• 🧰交互配置：支持 skill 的 AI 助手可安装仓库内置的 ssh-mcp-helper 技能，通过问答自动生成上述任一方式的配置
• 📖完整文档：更多参数（代理、2FA、堡垒机 shell 模式等）详见 README.md 的「多 SSH 连接配置」章节

一句话总结：主机少且已配好 SSH config，用方式四最爽；主机多、策略杂，直接上方式一的--config-file，其余两种按需取用。