ssh-mcp-server
给 AI 一把带保险栓的服务器钥匙 🔑
让 ZCode / Claude Code / Codex 等任何 MCP 客户端安全地登上你的服务器执行命令、传文件、跑任务—— 而服务器的 22 端口,从头到尾不需要对 AI(或互联网)开放。
Power your agent
पब्लिशर का इंस्टॉल। PlugMCP एंडपॉइंट नहीं।
Host a copy with our keys and logs.
रजिस्ट्री में अभी कोई पैकेज्ड रिलीज़ नहीं है। रिपॉज़िटरी का README देखें.
रिमोट URL या आपकी मशीन पर कमांड? दोनों इंस्टॉल में क्या अंतर है
PlugMCP पर चलाएँ
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
लॉन्च┌──────────────┐ HTTPS + Bearer Token ┌──────────────────────┐ SSH(22) ┌──────────────┐
│ AI 客户端 │ ──────────────────────→ │ Nginx → 本网关(单文件)│ ─────────────────→ │ 内网服务器 ×N │
│ ZCode/Claude │ 唯一暴露的口子 │ 部署在任一台可达机器上 │ 22 只对网关放行 │ 低权限账号落地 │
└──────────────┘ └──────────────────────┘ └──────────────┘
三个一句话卖点:
一句话:堡垒机管的是"人干了什么",ssh-mcp-server 管的是"AI 能干什么、不能干什么"。它不替代堡垒机——很多团队把它部署在堡垒机之后,作为 AI 专属的那一层。
六个 MCP 工具(一个 443 端口全部搞定):
两个流式端点(不走 MCP、不经 base64 膨胀):
POST /upload:GB 级文件流式上传,默认上限 3GiB 可调更大,恒定内存,返回远端 md5GET /download:不限大小流式下载,响应头 X-Md5 / X-File-Size 先行供校验其他内建能力:执行超时、输出截断(保头 60% + 尾 40%,防撑爆 AI 上下文)、SSH 并发上限、连接失败自动重试。
任何支持 MCP 的客户端都能接:ZCode、Claude Code、Codex、Cursor、Cline…… 配置一次,之后所有运维都是"说人话"。
场景 1 · 运维副驾驶——对话即操作:
「看下 web1、web2 的磁盘占用,超 80% 的把 /var/log 下 7 天前的日志清了」
AI 自己调 list_servers → 逐台 run_command → 汇总结果给结论。你不用登任何一台机器。
场景 2 · 代码改完直接上天——开发到部署零切换:
「这个 bug 修好了,发到测试机验证一下」
AI 在本地改代码 → 构建 → POST /upload 流式传包 → run_command 重启服务 → check_job/curl 验证 → 报告结果。全程没有人工 ssh,每一步都过安全防线、留审计。
场景 3 · 无人值守值班——把巡检交给定时任务:
用 ZCode 的定时任务(或系统 cron 拉起 AI 客户端)每天凌晨自动巡检:磁盘/内存/证书到期/服务存活,异常时才把报告推给你。低权限 Token 限定了它即使"抽风"也只能在白名单机器上做白名单外的事——做不了。
场景 4 · 团队分级授权——每个人、每个 AI 客户端一张专属门禁卡:
给每个同事发独立的 hmacUsers Token(每天自动换、各自 secret、各自服务器白名单),命令在各自低权限 OS 账号上落地。实习生和运维总监看到的服务器列表都不一样;谁的车钥匙丢了,吊销一张卡即可,不影响别人。
接入配置:
ZCode(~/.zcode/cli/config.json 用户级,或项目级 .zcode/config.json,改完重启生效):
{
"mcp": {
"servers": {
"ssh-gateway": {
// 方式一:网关在本机(stdio)
"command": "node",
"args": ["/opt/ssh-mcp-server/server.js"]
// 方式二:网关在远程(HTTP,推荐生产)
// "type": "streamableHttp",
// "url": "https://mcp.example.com/mcp",
// "headers": { "Authorization": "Bearer <你的token>" }
}
}
}
}
Claude Code:
claude mcp add --transport http ssh-gateway "https://mcp.example.com/mcp" \
--header "Authorization: Bearer <你的token>"
其他 MCP 客户端(Cursor / Cline / Codex 等)按各自的 MCP 配置格式填同一个 URL + 同一个 Authorization Header 即可。
核心思路:不信任 AI 的任何一次输出。AI 生成的每一条命令都当作不可信输入,过完层层防线才落地,且落地账号本身就没有破坏力。
互联网请求
│
▼
┌─────────────────────────────────────────────────────────────┐
│ ① 传输层 Nginx 443 唯一入口(或内置 TLS)+ 可选 IP 白名单 │
├─────────────────────────────────────────────────────────────┤
│ ② 身份层 Bearer Token:多静态 / HMAC 按天轮换 / 每人独立 │
│ 失败统一 401,不泄露任何凭据状态 │
├─────────────────────────────────────────────────────────────┤
│ ③ 防爆破层 双维计数(IP×凭据) → 封 IP/封组合 → 429+Retry-After │
│ trustedProxies 防伪造头绕过 / banAllowlist 管理网段 │
├─────────────────────────────────────────────────────────────┤
│ ④ 授权层 Token 级服务器白名单:越权目标"看不见",拒绝不泄露 │
├─────────────────────────────────────────────────────────────┤
│ ⑤ 命令防线 黑名单硬拦(引号/包裹变体防绕过,内置兜底+自定义合并)│
│ 高危命令二次确认:命中默认拒绝,confirm 复核才放行 │
├─────────────────────────────────────────────────────────────┤
│ ⑥ 文件防线 路径规范化/符号链接真实路径解析/敏感文件读写双拦 │
│ allowedFileRoots 目录白名单 / 原子覆盖 / 大小上限 │
├─────────────────────────────────────────────────────────────┤
│ ⑦ 执行层 专用低权限 OS 账号 + sudo 白名单落地(损害兜底) │
│ 超时 / 输出截断 / SSH 并发上限 / 主机指纹防中间人 │
├─────────────────────────────────────────────────────────────┤
│ ⑧ 审计层 JSONL 按天:谁、从哪个 IP、对哪台、执行了什么、 │
│ 返回了什么(结果摘要)——事后可完整追责 │
└─────────────────────────────────────────────────────────────┘
② 身份层——凭据不落配置、按天自换、可单独吊销
expiresAt 过期、disabled 禁用、新旧并存轮换)、HMAC 派生 Token(两端只存 master secret,Token 每天自动变,无需改配置重启)、hmacUsers 每人独立 secret(泄露一人只影响其自身白名单范围)SSH_MCP_TOKEN_FILE 从 0600 权限文件读 Token,group/other 可写直接拒绝启动expiresAt 解析失败按已过期处理、三类凭据全缺拒绝启动、非法/冲突配置拒绝启动——宁可起不来,绝不带病运行③ 防爆破层——在线暴露也不怕撞库
trustedProxies(IP/CIDR):只有 TCP 对端命中白名单才采信 X-Real-IP/X-Forwarded-For(取最右项)——伪造代理头无法再洗白限速计数banAllowlist 管理网段永不计数,防攻击者故意触发封禁把管理员锁在门外⑤ 命令防线——假设 AI 总有一天会写出 rm -rf /
rm -rf / 及其变体、mkfs、dd 写盘、fork 炸弹、shutdown、chmod -R 777 /、kill -9 -1、清空磁盘设备……命中硬拒,confirm: true 也救不回bash -c "rm -rf /" 类引号包裹绕过),不依赖部署方更新配置rm -rf 变体、shred、find / -delete、系统关键文件重定向等命中默认拒绝并返回命中说明,AI 复核确认(confirm: true)后才执行——误操作有人工节拍,破坏操作无豁免⑥⑦ 文件与执行——就算防线全过,落地账号也掀不起浪
/etc/shadow、authorized_keys、sshd_config、/boot 等../重复斜杠,在目标机解析符号链接真实路径后再校验 allowedFileRootsscripts/setup-limited-user.sh 一键创建 AI 专用低权限账号(sudoers 强制 --no-pager,防分页器逃逸提权)tail -f 拖死网关、防超大输出撑爆 AI 上下文⑧ 审计层——每一笔都有账
audit.enabled 开启后 JSONL 按天落盘:调用者身份、来源 IP、目标服务器、命令全文、返回结果摘要(头 1024 + 尾 256 字符,可调/可关)。不记文件内容与 Token 原值,审计日志本身不成为新的泄密点。
X-Powered-By 框架指纹头,不向探测方暴露技术栈scripts/setup-limited-user.sh 一键搞定)SSH_MCP_TRUST_PROXY=1)hmacUsers 每人独立 secretnpm install
cp config.example.json config.json
# 编辑 config.json:把 servers[0] 换成你的服务器(host/username/privateKeyPath,
# config.json 已 gitignore,不会误提交真实环境信息)
node test-direct.js # 直连测试(不走 MCP)
node test-mcp.js # stdio MCP 协议测试
node test-http.js # HTTP 网关模式测试(含 401 鉴权验证)
环境要求:Node.js >= 20(实测 node 18 下 MCP SDK 1.30 的 HTTP 模式会报
crypto is not defined,Ubuntu apt 版 node 尤其注意;SEA 产物自带运行时无此问题)。
打包成一个自带 Node 运行时的可执行文件(约 120MB),服务器上不需要安装 Node/npm/任何依赖。在任意 Linux 机器(或 WSL,需 Node >= 20)上执行:
bash scripts/build-linux.sh
# 产物:dist/ssh-mcp-server-linux
部署只需两个文件:
scp dist/ssh-mcp-server-linux config.json user@your-server:/opt/ssh-mcp/
# 服务器上:
cd /opt/ssh-mcp && chmod +x ssh-mcp-server-linux
SSH_MCP_TRANSPORT=http SSH_MCP_TOKEN=<你的强随机token> ./ssh-mcp-server-linux
配置文件查找顺序:SSH_MCP_CONFIG 环境变量 → 可执行文件同目录 → 当前目录。
systemd 里把 ExecStart 指向该二进制即可(其余环境变量同下表)。
打包机需要网络(npm 拉取 esbuild/postject),产物服务器完全离线可用。 Windows 版可参照脚本在 Windows 上用相同流程(postject 支持 PE 注入)。
# 1. 拷贝整个目录到服务器(Node.js >= 20)
npm install --omit=dev
# 2. 生成一个强随机 Token(或 node scripts/gen-token.js)
openssl rand -hex 32
# 3. 启动
SSH_MCP_TRANSPORT=http \
SSH_MCP_HOST=127.0.0.1 \
SSH_MCP_PORT=8080 \
SSH_MCP_TOKEN=<你的token> \
node server.js
# /etc/systemd/system/ssh-mcp.service
[Unit]
Description=SSH MCP Gateway
After=network.target
[Service]
WorkingDirectory=/opt/ssh-mcp-server
ExecStart=/usr/bin/node server.js
Environment=SSH_MCP_TRANSPORT=http
Environment=SSH_MCP_HOST=127.0.0.1
Environment=SSH_MCP_PORT=8080
Environment=SSH_MCP_TOKEN=换成你的强随机token
Restart=always
[Install]
WantedBy=multi-user.target
systemctl daemon-reload && systemctl enable --now ssh-mcp
# /etc/nginx/conf.d/ssh-mcp.conf
server {
listen 443 ssl;
server_name mcp.example.com;
ssl_certificate /etc/letsencrypt/live/mcp.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/mcp.example.com/privkey.pem;
# 可选:再加一层 IP 白名单
# allow 你的出口IP;
# deny all;
location /mcp {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
# MCP 可能为长连接响应,关闭缓冲
proxy_buffering off;
proxy_cache off;
proxy_read_timeout 660s;
# 重要:upload_file 的内容走 base64(体积膨胀约 1/3),
# 默认上限 5MB 文件需要 ~10m 的 body 限制
client_max_body_size 10m;
}
# 大文件流式上传(可选启用):按 maxStreamUploadBytes 放开 body 限制
location /upload {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_request_buffering off; # 流式透传,不在 Nginx 落盘
client_max_body_size 0; # 0 = 不限;或按 maxStreamUploadBytes 设置
proxy_read_timeout 3600s;
}
}
AI 客户端最终访问:https://mcp.example.com/mcp
MCP 的 upload_file/download_file 走 base64/JSON,只适合中小文件。GB 级文件用网关流式端点,
请求/响应体直接在网关与目标机 SFTP 之间搬运(恒定内存、不经 MCP、返回远端 md5):
TOKEN=<你的token>
# POST(curl 会流式读文件,不占内存)
curl -X POST -H "Authorization: Bearer $TOKEN" \
--data-binary @bigfile.iso \
"http://127.0.0.1:18080/upload?path=/opt/bigfile.iso"
# PUT 语义等价:curl -T bigfile.iso -H "..." "http://.../upload?path=/opt/bigfile.iso"
# 可选参数:&server=<服务器id>&mode=0600
下载同样流式(SFTP 读流直透响应,不限大小,响应头 X-Md5/X-File-Size 先行供校验):
curl -H "Authorization: Bearer $TOKEN" -o bigfile.iso \
"http://127.0.0.1:18080/download?path=/opt/bigfile.iso"
上限由 config.json 的 defaults.maxStreamUploadBytes 控制(默认 3GiB=3221225472,可调更大)。
云服务器安全组只需放行 443(或 80)一个端口——六个 MCP 工具 (run_command / check_job / kill_job / upload_file / download_file / list_servers) 与两个流式端点(/upload、/download)都经由这同一个端口完成,经 Nginx 反代即可使用。
{
"servers": [ // 多台服务器随便加
{
"id": "web1", // AI 调用时引用的 ID
"name": "官网生产机", // 备注名
"host": "10.0.0.11", // 内网地址(只要网关机器能连到)
"port": 22,
"username": "deploy", // 建议专用低权限账号
"privateKeyPath": "~/.ssh/id_ed25519",
"hostFingerprint": "SHA256:xxxx", // 可选:SSH 主机指纹校验
"allowedFileRoots": ["/opt/apps", "/tmp"] // 可选:限制文件操作目录(含符号链接真实路径)
}
],
"defaults": {
"serverId": "web1", // run_command 不传 server 时的默认目标
"timeoutMs": 30000, // 命令超时
"maxOutputBytes": 65536, // 输出截断上限(防撑爆 AI 上下文)
"maxUploadBytes": 5242880, // 单文件上传上限(5MB)
"maxDownloadBytes": 524288, // 单文件下载上限(512KB)
"maxStreamUploadBytes": 3221225472, // /upload 流式上传上限(3GiB,可调更大)
"maxConcurrentSsh": 10 // 全局 SSH 连接并发上限
},
"blockedPathPatterns": [ // 敏感路径黑名单(读写均拦截)
"^/etc/(passwd|shadow|gshadow|sudoers)",
"^/etc/ssh/sshd_config",
"authorized_keys$",
"known_hosts$",
"^/boot/"
],
"blockedCommandPatterns": [ // 危险命令黑名单(正则,忽略大小写;与内置兜底合并生效)
"rm\\s+-[a-zA-Z]*[rf][a-zA-Z]*\\s+/(\\s|$|\\*)",
"\\bmkfs(\\.\\w+)?\\b",
"\\bdd\\b[^|]*if=/dev/(zero|random)",
"\\bdd\\b[^|]*of=/dev/(sd|hd|nvme|vd)",
":\\(\\)\\s*\\{.*\\};\\s*:",
"\\b(shutdown|reboot|halt|poweroff)\\b",
"\\binit\\s+[06]\\b",
">\\s*/dev/sd[a-z]",
"chmod\\s+(-[a-zA-Z]+\\s+)*777\\s+/(\\s|$)",
"pkill\\s+(-[a-zA-Z0-9]+\\s+)*-f\\s+(['\"]{0,2})\\s*$",
"\\bkill\\s+(-9\\s+)?-1\\b",
"\\bkill\\s+--\\s+-1\\b"
],
"auth": { // HTTP 鉴权(可选;与 SSH_MCP_TOKEN 并存,全缺时拒绝启动)
"trustedProxies": ["127.0.0.1"], // 采信 X-Real-IP/XFF 的反代网段(IP/CIDR)
"banAllowlist": ["10.0.0.0/24"], // 封禁豁免网段:永不计数、永不 429
"confirmPatterns": [ // 可选:高危命令二次确认清单(显式配置即完全覆盖默认清单)
"rm\\s+-[a-zA-Z]*[rf]",
"shred\\s",
"find\\s+/.*-delete"
],
"tokens": [ // 多静态 Token:按 id 区分调用方,支持过期/禁用/服务器白名单
{ "id": "alice", "token": "<64位hex>", "note": "主力客户端" },
{ "id": "old", "token": "<64位hex>", "expiresAt": "2026-10-01T00:00:00Z" },
{ "id": "emp", "token": "<64位hex>", "servers": ["self-limited"] } // 该 Token 只能访问指定服务器
],
"hmac": { // HMAC 派生 Token 自动轮换(scripts/derive-token.js 推导)
"secret": "<master-secret>", // 注意:全局派生 Token 不受 servers 白名单限制,仅发可信调用方
"periodHours": 24, // 时间桶周期,默认 24h
"graceBuckets": 1 // 接受当前桶 ±N,默认 1
},
"hmacUsers": [ // 每人独立 HMAC secret:自动轮换 + 各自服务器白名单(两全)
{ "id": "emp-alice", "secret": "<每人独立随机串>", "servers": ["self-limited"] }
],
"rateLimit": { "windowMs": 60000, "maxFails": 10, "banMs": 600000 } // 防爆破
},
"audit": { "enabled": true, "dir": "/var/log/ssh-mcp" } // 审计日志(默认关闭;JSONL 按天)
}
获取目标机 SSH 指纹(建议从可信网络或服务器控制台核对):
ssh-keyscan -t ed25519 10.0.0.11 2>/dev/null | ssh-keygen -lf - -E sha256
Set-NetFirewallHyperVVMSetting -Name '{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}' -DefaultInboundAction Allow
(改回 Block 即可还原)bash scripts/start-wsl-test.sh,它会重启 WSL、更新 config.json 里的 IP
并连跑三个测试。生产部署在真实 Linux 服务器上不存在这些问题。见 CHANGELOG.md(当前 0.4.1)。
AI 的 SSH 网关:让 ZCode/Claude Code/Codex 等 AI 客户端通过 MCP 安全地执行远程命令与传输文件
टूल
अभी टूल सूची नहीं है। रिमोट सर्वर को पहले हेल्थ चेक के बाद सूची मिलती है।
FAQ
इस पेज पर Cursor, Claude Desktop, Claude Code या VS Code के लिए stdio कॉन्फ़िग कॉपी करें। यह पब्लिशर का इंस्टॉल इस्तेमाल करता है, PlugMCP प्रॉक्सी नहीं।
इस रिकॉर्ड में कोई ज़रूरी एनवायरनमेंट वेरिएबल दर्ज नहीं है।
Ssh stdio पर लोकल चलता है।
पिछली जाँच 2026-10-28 को हुई। AI 的 SSH 网关:让 ZCode/Claude Code/Codex 等 AI 客户端通过 MCP 安全地执行远程命令与传输文件