classfang/ssh-mcp-server/ssh-mcp-helper

ssh-mcp-helper

概述

帮助用户通过交互式问答完成 @fangjunjie/ssh-mcp-server 的安装预检与 MCP 客户端配置。技能本身不代替用户输入凭据，而是逐项确认认证方式、连接参数与安全策略，最终产出可直接写入 MCP 客户端配置文件的 mcpServers JSON 片段。

核心准则： 所有可枚举的选项（MCP 客户端类型、认证方式、传输模式、是/否开关）必须使用 AskUserQuestion 让用户选择；只有不可枚举的输入（host、用户名、私钥路径、密码、自定义白名单正则等）才允许自由文本提问。

何时使用

• 用户明确要安装/配置/新增 ssh-mcp-server
• 用户提到为 Cursor / Claude Code / Cline / Continue 等客户端添加 SSH MCP
• 用户希望在已有 mcpServers 中追加一台 SSH 主机
• 用户问「ssh-mcp-server 的 mcp.json 怎么写」

何时不使用

• 用户要修改 ssh-mcp-server 源码 → 直接编辑代码，不进入向导
• 用户只是想跑某条 SSH 命令 → 直接调用已存在的 ssh-mcp-server 工具
• 用户在问 SSH 协议本身的概念 → 解释即可，无需走流程

工作流程

digraph ssh_mcp_helper {
    "0. 前置环境检查" [shape=box];
    "1. 选择 MCP 客户端" [shape=box];
    "2. 单台 vs 多台" [shape=diamond];
    "3. 选择认证方式" [shape=box];
    "4. 询问连接参数" [shape=box];
    "5. 询问高级选项" [shape=box];
    "6. 生成 JSON 片段" [shape=box];
    "7. 合并写入配置" [shape=box];
    "8. 提示重启与验证" [shape=doublecircle];
 
    "0. 前置环境检查" -> "1. 选择 MCP 客户端";
    "1. 选择 MCP 客户端" -> "2. 单台 vs 多台";
    "2. 单台 vs 多台" -> "3. 选择认证方式" [label="单台"];
    "2. 单台 vs 多台" -> "3. 选择认证方式" [label="多台 → 写 ssh-config.json"];
    "3. 选择认证方式" -> "4. 询问连接参数";
    "4. 询问连接参数" -> "5. 询问高级选项";
    "5. 询问高级选项" -> "6. 生成 JSON 片段";
    "6. 生成 JSON 片段" -> "7. 合并写入配置";
    "7. 合并写入配置" -> "8. 提示重启与验证";
}

Step 0：前置环境检查

• 运行 node -v 与 npx --version 确认本机有 Node.js（推荐 v18+）
• 缺失则先提示用户安装 Node.js，再继续后续步骤

Step 1：选择 MCP 客户端（AskUserQuestion 多选一）

Step 2：单台 vs 多台（AskUserQuestion 二选一）

• 单台：直接使用命令行参数（--host 等）
• 多台：生成 ssh-config.json 并使用 --config-file

Step 3：选择认证方式（AskUserQuestion 多选一）

• password — 账号 + 密码
• privateKey — 账号 + 私钥；再用 AskUserQuestion 确认是否带 passphrase
• ssh-config — 复用 ~/.ssh/config 中的 Host 别名（只需 --host <alias>，可选 --ssh-config-file）
• ssh-agent — 使用 --agent 指向 socket
• 2fa — 密码 + 私钥 + 键盘交互，追加 --try-keyboard

Step 4：连接参数（自由文本）

• host / port / username（port=22 可省略）
• 按 Step 3 的结果追问密码、私钥路径、passphrase、agent socket 等

Step 5：高级选项（每项独立用 AskUserQuestion 询问是/否）

1. SOCKS 代理：是 → 追问 --socksProxy 字符串
2. 命令白名单：是 → 追问逗号分隔正则（生产环境强烈建议开启）
3. 命令黑名单：是 → 追问逗号分隔正则
4. 命令模板：是 → 追问含 <command> 占位符的模板
5. 传输模式：默认 exec；若用户标记目标为堡垒机/跳板机，改 shell 并追问 --shell-ready-timeout
6. 路径白名单：是 → 追问 --allowed-local-paths / --allowed-remote-paths
7. 启动时预连接：是 → 追加 --pre-connect
8. MCP 接入方式：默认 stdio（客户端拉起进程）。若选 HTTP：

• 启动命令追加 --mcp-transport http，并建议设置 SSH_MCP_HTTP_TOKEN（或 --http-token）
• 客户端配置使用 url 与可选的 headers.Authorization，形式为 Bearer <token>
• 提醒用户先单独启动 ssh-mcp-server 进程，再让客户端连接该 URL
• 默认只监听 127.0.0.1:3000，路径 /mcp；监听非本机地址时启动日志会警告，应同时配置令牌

Step 6：生成 JSON 片段

装配规则：

• stdio：command 固定为 "npx"，args 第一项 "-y"，第二项 "@fangjunjie/ssh-mcp-server"
• http：客户端片段使用 url；有令牌时加上 headers.Authorization。另外单独给出启动进程的命令，令牌放在环境变量 SSH_MCP_HTTP_TOKEN 中
• 每个命令行参数与值必须是 args 数组中独立的两个元素，绝不能写成 "--host 192.168.1.1"
• 多连接场景：把每个连接写入 ssh-config.json（数组或对象格式皆可）。stdio 的客户端配置里放 --config-file <绝对路径>；http 则把该参数放进单独的启动命令

Step 7：合并写入配置

• 先用 Read 读取目标 JSON 配置文件
• 合并到既存 mcpServers 下；若存在同名 key，先 AskUserQuestion 让用户选择覆盖 / 改名 / 取消
• 写入前把最终片段展示给用户确认
• 写入后输出该配置文件的绝对路径

Step 8：收尾

• 提示用户重启对应 MCP 客户端使配置生效
• 给出验证方式：调用 list-servers，或对该连接执行 execute-command "whoami"

速查表

常见坑

• ❌ 把 "--host 192.168.1.1" 当作一个 args 元素 → ✅ 拆成两个元素 "--host", "192.168.1.1"
• ❌ 密码含 { } = , 等字符却用旧式 --ssh "name=...,password=..." → ✅ 改用 --config-file 或 JSON 形式 --ssh
• ❌ shell 模式下还想用 upload/download → 该模式禁用 SFTP，需切回 exec
• ❌ 直接覆盖用户既有 mcpServers 中的同名 key → 必须先读后合并，覆盖前显式确认
• ❌ 直连生产环境却未配置 --whitelist / --blacklist → 必须主动提醒安全风险
• ❌ 把私钥内容粘进配置 → 配置里应填私钥文件路径，凭据留在本地

输出示例

最简单的账号密码场景产出：

{
  "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_./-]+$"
      ]
    }
  }
}

HTTP 接入时，进程单独启动，客户端只保存 URL：

{
  "mcpServers": {
    "ssh-mcp-server": {
      "url": "http://127.0.0.1:3000/mcp",
      "headers": {
        "Authorization": "Bearer replace-with-a-long-random-token"
      }
    }
  }
}

对应启动命令在参数中加上 --mcp-transport http，令牌通过 SSH_MCP_HTTP_TOKEN 传入。

多连接场景产出 ssh-config.json + 简化的客户端配置：

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