一、项目概述
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 桌面应用中配置步骤如下：
- 打开 CC Switch → 点击“MCP”标签页
- 点击“Add Server”或“添加服务器”
- 选择传输类型为stdio（ssh-mcp-server 基于标准输入输出通信）
- 填写配置信息：
- Name:
ssh-mcp-server（或自定义，如homelab-server） - Command:
npx - Args: 按上述 JSON 格式逐行填入参数
- Name:
- 启用该服务器，并选择需要同步的 AI 客户端（如 Claude Code、Cursor）
- 重启对应 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_rsa5.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、downloadshell：通过持久 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
