一、项目概述

ssh-mcp-server 是一个基于 SSH 的 Model Context Protocol (MCP) 服务端实现，由开发者 classfang（方俊杰）开源维护。它充当了 AI 助手与远程服务器之间的安全桥梁，让支持 MCP 协议的客户端（如 Claude Code、Cursor、Cline、CC Switch 等）能够通过标准化接口执行远程 SSH 命令、上传/下载文件，而无需将 SSH 凭据直接暴露给 AI 模型。

核心定位：credential 隔离 + 命令安全管控 + 标准化协议封装。

项目地址：classfang/ssh-mcp-server | NPM: @fangjunjie/ssh-mcp-server

---

二、核心特性

特性	说明
🔒 安全连接	支持密码认证、私钥认证（含 passphrase）、SSH Agent、双因素认证(2FA)
🛡️ 命令安全控制	通过白名单/黑名单机制精确控制可执行命令范围，防止误操作
🔄 标准化接口	完全兼容 MCP 协议规范，无缝对接各类 MCP 客户端
🚇 双传输模式	exec 模式（默认，支持文件传输）与 shell 模式（跳板机/堡垒机场景）
📂 文件传输	支持双向 SFTP 文件上传与下载
🔑 凭据隔离	SSH 凭据完全本地管理，AI 模型无法直接接触
🚀 即开即用	通过 NPX 直接运行，无需全局安装

---

三、工具列表

工具名	功能描述
execute-command	在远程服务器上执行 SSH 命令并返回结果
upload	将本地文件上传至远程服务器指定路径
download	从远程服务器下载文件到本地指定路径
list-servers	列出所有已配置的 SSH 服务器连接

---

四、CC Switch 中如何配置

CC Switch 是一款开源的跨平台 AI CLI 统一管理工具，支持 Claude Code、Codex、Gemini CLI、OpenCode、Cursor 等多种 AI 编程助手。它通过 SQLite 数据库集中管理 MCP 服务器配置，支持 stdio、HTTP、SSE 三种传输类型，并能实现多应用间的双向同步。

在 CC Switch 中配置 ssh-mcp-server 时，本质上是将 MCP 服务器的 stdio 配置写入其内部数据库，然后由 CC Switch 代理转发给底层 AI 客户端。

4.1 基础配置（用户名+密码）

基础配置示例，适用于最常见的密码认证场景：

{
  "command": "npx",
  "args": [
    "-y",
    "@fangjunjie/ssh-mcp-server",
    "--host", "192.168.3.6",
    "--port", "22",
    "--username", "root",
    "--password", "root"
  ]
}

配置要点解析：

• command: npx — 使用 Node.js 的包执行器，无需全局安装
• -y — 自动确认安装，避免交互式提示阻塞
• @fangjunjie/ssh-mcp-server — 指定 NPM 包名，每次运行自动拉取最新版本
• --host, --port, --username, --password — 标准 SSH 连接四元组
• ⚠️ 关键格式：每个参数和值必须是 args 数组中的独立元素，禁止合并为 "--host 192.168.3.6"

4.2 CC Switch 配置入口

在 CC Switch 桌面应用中配置步骤如下：

1. 打开 CC Switch → 点击 “MCP” 标签页
2. 点击 “Add Server” 或 “添加服务器”
3. 选择传输类型为 stdio（ssh-mcp-server 基于标准输入输出通信）
4. 填写配置信息：
   • Name: ssh-mcp-server（或自定义，如 homelab-server）
   • Command: npx
   • Args: 按上述 JSON 格式逐行填入参数
5. 启用该服务器，并选择需要同步的 AI 客户端（如 Claude Code、Cursor）
6. 重启对应 AI 客户端使配置生效

CC Switch 会自动将配置同步到各客户端的配置文件中（如 Claude Code 的 ~/.claude/mcp.json 或 Cursor 的 .cursor/mcp.json），无需手动编辑。

---

五、进阶配置场景

5.1 私钥认证（推荐生产环境使用）

相比密码认证，私钥认证更安全，且支持 passphrase 保护：

{
  "command": "npx",
  "args": [
    "-y",
    "@fangjunjie/ssh-mcp-server",
    "--host", "192.168.3.6",
    "--port", "22",
    "--username", "root",
    "--privateKey", "~/.ssh/id_rsa",
    "--passphrase", "your_key_passphrase"
  ]
}

5.2 复用 ~/.ssh/config

如果你已在 ~/.ssh/config 中配置了主机别名，可直接复用：

{
  "command": "npx",
  "args": [
    "-y",
    "@fangjunjie/ssh-mcp-server",
    "--host", "myserver"
  ]
}

对应的 ~/.ssh/config：

Host myserver
    HostName 192.168.3.6
    Port 22
    User root
    IdentityFile ~/.ssh/id_rsa

5.3 命令白名单/黑名单（安全加固）

强烈建议在生产环境中启用命令限制，防止 AI 误执行危险操作：

白名单模式（仅允许只读命令）：

{
  "command": "npx",
  "args": [
    "-y",
    "@fangjunjie/ssh-mcp-server",
    "--host", "192.168.3.6",
    "--port", "22",
    "--username", "root",
    "--password", "root",
    "--whitelist", "^ls( .*)?,^cat .*,^df.*,^ps .*,^top.*"
  ]
}

黑名单模式（禁止高危命令）：

{
  "command": "npx",
  "args": [
    "-y",
    "@fangjunjie/ssh-mcp-server",
    "--host", "192.168.3.6",
    "--port", "22",
    "--username", "root",
    "--password", "root",
    "--blacklist", "^rm .*,^shutdown.*,^reboot.*,^mkfs.*,^dd .*"
  ]
}

规则说明：白名单和黑名单均使用逗号分隔的正则表达式。若同时配置，命令需同时通过两项检查（先白名单，后黑名单）。

5.4 跳板机/堡垒机（shell 模式）

当目标服务器仅暴露交互式 Shell（如堡垒机、网络设备）时，需切换为 shell 模式：

{
  "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"
  ]
}

模式差异：

• exec（默认）：支持 execute-command、upload、download
• shell：通过持久 Shell 会话执行命令，不支持文件传输（SFTP 不可用）

5.5 多服务器管理

当需要同时管理多台服务器时，推荐使用配置文件方式：

创建 ssh-config.json：

[
  {
    "name": "homelab",
    "host": "192.168.3.6",
    "port": 22,
    "username": "root",
    "password": "root"
  },
  {
    "name": "prod-web",
    "host": "10.0.0.5",
    "port": 22,
    "username": "deploy",
    "privateKey": "~/.ssh/prod_key",
    "whitelist": "^ls( .*)?,^cat .*,^systemctl .*"
  }
]

CC Switch 配置：

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

使用时在 AI 对话中指定 connectionName：

在 prod-web 上执行 df -h