Ssh Mcp Server

@nl4ever/sshmcp

中文文档

让 AI 管理你的远程服务。 一个模型上下文协议（MCP）服务，为 AI 助手提供完整的 SSH 访问权限——通过自然对话执行命令、传输文件并同时管理多台服务。

You:   "Deploy the latest build to production server"
AI:    connects → uploads build → restarts service → verifies status

功能特性

• 21 个工具 — 连接、执行、上传、下载、写入文件等
• 连接池 — 同时操作多台服务，每条命令都带有 server_id
• 零令牌文件传输 — 基于 SFTP 路径传输，文件内容不会进入 AI 上下文
• 目录上传 — 自动 tar.gz 压缩 → 上传 → 远程解压（适合快速传输大量小文件）
• 异步传输 + 进度 — 在后台传输大文件，并实时跟踪进度
• 快速连接 — 无需保存配置即可建立临时连接，并返回 host:port 作为临时 ID
• SOCKS4/5 代理 — 支持为每个连接单独配置代理
• 跳板服务 — 通过 SSH ProxyJump 访问堡垒机/网关
• 多种认证方式 — 密码、私钥、ssh-agent、键盘交互（OTP/2FA）

快速开始

全局安装

npm install -g @nl4ever/sshmcp

添加到 Claude Code

claude mcp add sshmcp sshmcp

添加到 Claude Desktop

编辑 claude_desktop_config.json：

{
  "mcpServers": {
    "sshmcp": {
      "command": "npx",
      "args": ["-y", "@nl4ever/sshmcp"]
    }
  }
}

添加到 Cursor

前往 Settings → MCP Servers → Add：

{
  "sshmcp": {
    "command": "npx",
    "args": ["-y", "@nl4ever/sshmcp"]
  }
}

工具概览

连接管理

工具	描述
list_servers	列出所有已配置的服务和活动连接
get_server	查看服务配置详情
add_server	添加/更新服务配置（密码、密钥、Agent、OTP）
update_server	修改服务配置（只需传入要更改的字段）
delete_server	移除服务
rename_server	重命名服务 ID
connect	手动连接（通常无需使用，工具会自动连接）
quick_connect	临时连接，返回 host:port 作为 ID
disconnect	断开指定服务或所有连接
test_connection	测试连接，不影响现有连接

命令执行

工具	描述
execute	在远程服务上运行 Shell 命令（可配置超时）

文件操作

工具	描述
read_file	读取远程文件内容（可选行范围）
write_file	将文本内容写入远程文件
upload_file	将本地文件上传到远程服务（支持异步模式）
upload_directory	上传目录，自动压缩 → 传输 → 解压
download_file	将远程文件下载到本地（支持异步模式）
download_directory	下载目录，远程压缩 → 传输 → 本地解压
transfer_status	查看异步传输进度（大小/速度/预计剩余时间）

代理管理

工具	描述
list_proxies	列出所有 SOCKS 代理预设
add_proxy	添加 SOCKS4/5 代理预设
delete_proxy	移除代理预设

连接池：多服务操作

所有操作工具都需要 server_id 参数。连接池会自动管理连接，无需手动连接/断开：

AI: execute(server_id="prod", command="nginx -s reload")         ← auto-connects to prod
AI: execute(server_id="dev", command="tail -f /var/log/app.log") ← auto-connects to dev, prod stays
AI: execute(server_id="prod", command="curl localhost")           ← reuses prod connection

对于临时服务，可使用 quick_connect，它会返回 host:port 作为 ID：

AI: quick_connect(host="1.2.3.4", username="root", password="***")
→ "Connected: [email protected]:22, use server_id="1.2.3.4:22""

AI: execute(server_id="1.2.3.4:22", command="df -h")
AI: disconnect(server_id="1.2.3.4:22")

异步传输（大文件）

对于大文件，可启用后台传输模式，避免操作阻塞：

AI: upload_file(server_id="prod", local_path="big.tar.gz", remote_path="/data/", async_transfer=true)
→ "Background upload started: tf_1"

AI: transfer_status("tf_1")
→ "🔄 Uploading: 638.2 MB / 1.2 GB (53.2%) — 12.4 MB/s, ETA 46s"

AI: transfer_status("tf_1")
→ "✅ Upload complete: 1.2 GB, 98s, 12.3 MB/s"

小文件默认使用同步模式，无需配置。

连接示例

密码认证

AI: add_server(server_id="prod", name="Production", host="10.0.0.1", username="deploy", password="***")
AI: execute(server_id="prod", command="systemctl status nginx")

私钥认证

AI: add_server(server_id="aws", name="AWS EC2", host="ec2-xx.compute.amazonaws.com", username="ubuntu", private_key="~/.ssh/id_rsa")

快速连接（不保存配置）

AI: quick_connect(host="192.168.1.100", username="root", password="***")
→ server_id="192.168.1.100:22"

AI: execute(server_id="192.168.1.100:22", command="df -h")
AI: disconnect(server_id="192.168.1.100:22")

通过 SOCKS5 代理连接

AI: add_proxy(proxy_id="tunnel", name="SSH Tunnel", host="127.0.0.1", port=1080, type="5")
AI: add_server(server_id="internal", ..., proxy="tunnel")

通过跳板服务连接

AI: add_server(server_id="bastion", name="Bastion", host="bastion.example.com", username="admin", private_key="~/.ssh/id_rsa")
AI: add_server(server_id="internal", name="Internal DB", host="10.0.0.5", username="dbadmin", password="***", jump_host="bastion")

配置位置

服务和代理配置存储在：

~/.ssh-mcp/config.json

密码以明文存储。生产环境建议优先使用私钥身份验证。

要求

• Node.js >= 18
• 兼容 MCP 的客户端（Claude Code、Claude Desktop、Cursor 等）
• 可通过 SSH 访问的远程服务

许可证

MIT