ssh
Provides SSH/SFTP access to Linux remote hosts for executing shell commands and transferring files, with structured exit codes, separated stdout/stderr, timeouts, output truncation, persistent sessions, host-key verification, and multi-host configuration.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
ssh-mcp
给 agent 用的 Linux 远端命令执行与文件传输工具:一个跑在 stdio 上的 MCP server。
它把「SSH 远程执行」收敛成一层薄桥:命令按原生 shell 写,桥只补 shell 给不了的东西——
认证与 host key 校验、连接复用、退出码与输出流的分离、输出预算与真实总量、跨调用的会话状态。
对外恰好两个工具:exec(执行)与 transfer(搬文件)。如果你希望 agent 在远端做事时
写的是 systemctl status nginx && journalctl -n 50 这样的原生命令、并且能对结果
(退出码/超时/截断)做判定而不是猜,这个桥就是为它做的。
设计判据与不变量见 docs/domain.md;对外契约由 test/contract.test.ts 锁定。
完整用法教学(正反例、会话、超时、传输案例)在随仓库发布的 skills/ssh-mcp/SKILL.md,
支持技能的客户端会自动注入它。
不调用系统
ssh/scp/sftp/plink子进程,不用 ControlMaster,除本 server 进程外不启动任何常驻后台进程。只支持 Linux 远端(Windows/macOS 本机侧)。
目录
Related MCP server: lms-ssh-client-mcp
安装
新机器推荐按 GitHub 仓库安装(不 clone):放 exe 一条命令、装 SKILL 一条命令;更新是重跑同两条命令,不用换 URL。
1. 产物(Windows x64)——固定名资产 ssh-mcp-windows-x64.zip 每个 Release 都挂,latest 永远指向最新版:
New-Item -ItemType Directory -Force $HOME/tools | Out-Null
if (Get-Process ssh-mcp -ErrorAction SilentlyContinue) { Stop-Process -Name ssh-mcp -Force } # Windows 不让覆盖正在运行的 exe,先解锁
Invoke-WebRequest https://github.com/UnaRem/ssh-mcp/releases/latest/download/ssh-mcp-windows-x64.zip -OutFile $HOME/tools/ssh-mcp.zip
Expand-Archive $HOME/tools/ssh-mcp.zip $HOME/tools -Force
Remove-Item $HOME/tools/ssh-mcp.zip产物是单文件 exe(含 bun 运行时与原生模块),解压即用,无需其它依赖。第一次启动会在 exe 同级自动生成
配置模板(见「配置」);编辑 ~/tools/config.local.json、把客户端 command 指向 exe(见「接入 MCP 客户端」)
即完成初始化。更新 = 重跑上面的命令,然后让客户端重连那条 MCP 连接。
2. SKILL——支持技能的客户端需要;从本仓库装进 ~/.agents/skills(pi/opencode/codex 共用的枢纽,
装完自动链到各客户端的技能目录):
npx -y skills add UnaRem/ssh-mcp -g -y
# 更新:npx skills update ssh-mcp -g -y走 skills CLI,按 lockfile 管理,update 会按记录源重新拉取仓库。
SKILL 与工具名由契约测试锁成同版(不变量 12),换 exe 时把它一起跑。
开发期(要改代码)才需要 clone 仓库;bun 版本实测 1.3.14:
方式 | 命令 | 适用 |
源码直跑 |
| 开发期(改代码即生效) |
本地构建产物 |
| 改动要在产物上验收 |
开发机的 SKILL 直接让客户端读仓库 skills/,或用 bun run sync-skill 拷到本机技能目录
(默认 ~/.agents/skills/ssh-mcp,--target 可指各客户端自己的目录)。注意别和 skills CLI 的托管混用:
sync-skill 只是拷贝、不进 lockfile,skills update 也不认它——装了哪种就用哪种的更新方式。
配置
凭据永不入库:含明文密码的只有 config.local.json(已被 gitignore)。
配置文件查找顺序(首次启动三处都没有时,会在最优可写位置生成模板,只创建不覆盖):
环境变量
SSH_MCP_CONFIG(绝对路径);可执行文件同级的
config.local.json—— 推荐,客户端里一条 env 都不用设;进程 cwd 下的
config.local.json(源码直跑场景;客户端的 cwd 不可靠,别依赖)。
config.local.json 形状(先 exec({}) 自省可以看到当前解析到的全部主机别名):
{
"defaults": { "host_key_policy": "tofu" },
"hosts": {
"lan": { "hostname": "192.168.1.21", "user": "unarem", "password": "…" },
"app": { "hostname": "10.0.0.5", "user": "deploy", "identity_files": ["~/.ssh/id_ed25519"], "host_key_policy": "strict" }
}
}字段:hostname port user password key_passphrase identity_files host_key_policy(tofu/strict/off);
defaults 会被具体 profile 覆盖。配置每次调用都重读,改完即时生效。
host 参数的解析顺序:profile 别名 → ~/.ssh/config 别名(读 HostName/User/Port/IdentityFile)→
直接写 192.168.1.21 / user@ip / host:port / user@[v6]:port。解析不出来会报错并列出全部可用别名。
认证:密钥优先、密码兜底(显式 publickey→password 顺序);绝不弹交互提示,缺凭据快速失败且原因可读
(auth_methods_attempted/auth_succeeded_with 来自协议实测)。
host key 自行校验(ssh2 本身不做):TOFU 首连记录、strict 必须有记录、off 不校验;known_hosts 只追加不改写。
凭据约束:密码/私钥不得暴露在公网。 只纳管局域网/组网内、网络层公网不可达的主机; 公网主机先组网(VPN/内网穿透)再纳管,不放宽这条约束。
接入 MCP 客户端
所有客户端配置形状相同,command 指向源码(经 bun)或 exe 都可以;用绝对路径——客户端工作目录不确定。
{
"mcpServers": {
"ssh": {
"command": "C:/Users/<you>/.bun/bin/bun.exe",
"args": ["run", "C:/absolute/path/to/ssh-mcp/src/index.ts"],
"env": { "SSH_MCP_CONFIG": "C:/absolute/path/to/ssh-mcp/config.local.json" }
}
}
}客户端可见的工具名 = 客户端侧命名空间 + 工具原名:
PI-Desktop 等取服务端身份名(
src/index.ts的new McpServer({ name: "ssh" }))→ 可见名mcp_ssh_exec/mcp_ssh_transfer;OpenCode 取客户端配置里的 mcp 键,不读服务端身份名。
改过工具名或身份名后,要在客户端删掉旧登记并重启/重连(工具目录不自动刷新):
自检办法是调 exec({}),返回里带 mode:"inventory" 与 hint 才是新工具面。
用法
exec —— 远端执行
不传任何参数 = 自省:返回主机清单与来源、配置路径、活动连接与会话。
// 一条命令完成多步(一次往返)
{ "host": "lan", "command": "cd /srv/app && git pull && systemctl restart app && systemctl is-active app" }
// 长任务:起后台再轮询,不要把 timeout_ms 调大(默认 5000ms 即上限,只能调小)
{ "host": "lan", "command": "nohup ./deploy.sh > /tmp/deploy.log 2>&1 & echo $!" }
{ "host": "lan", "command": "tail -n 50 /tmp/deploy.log; kill -0 12345 && echo RUNNING || echo DONE" }
// 跨调用保持 cwd 与 export:session="keep",返回 session_id,后续调用带上它
{ "host": "lan", "command": "export DEPLOY=staging && cd /srv/app", "session": "keep" }参数:host、command、session(keep 或 session_id)、session_op(reset/close)、
cwd/env(建会话时的起始状态)、timeout_ms/max_output_bytes(本次调用的上限,只能调小)。
transfer —— 本机与远端之间搬文件
{ "host": "lan", "entries": [
{ "op": "put", "local_path": "C:/tmp/app.tar", "remote_path": "/tmp/app.tar" },
{ "op": "get", "remote_path": "/var/log/app.log", "local_path": "C:/tmp/app.log", "overwrite": true }
] }多条目共用一条 SFTP 连接、按请求顺序返回;每条回报两端字节数与 bytes_match,本机文件另给 sha256。
默认不覆盖已存在的目标(overwrite=true 才覆盖)。列目录、看属性、读文本、建目录请改用远端
ls/stat/sed -n/cat/mkdir -p——它们更贴近模型既有能力,所以不做成工具。
更多正反例(含超时、会话、失败条目处理)见 skills/ssh-mcp/SKILL.md。
返回语义与错误码
成功调用:
ok: true+ JSON(同时提供structuredContent)。 命令退出码非 0 不是工具错误:isError=false、顶层ok=false——按exit_code/stderr判定。工具错误:
isError=true+ 稳定的error_code+ 补救所需的事实(未知主机回清单、未知会话回active_sessions)。超时:
timed_out=true时已到达的输出原样带回;桥只是停止等待,不会终止远端命令—— 要限制时长在命令里写timeout <秒> …,要跑得更久就起后台再轮询。timeout_ms默认即上限(5000ms), 超出只截不拒并在结果里可见(timeout_ms_requested/timeout_capped)。截断:
truncated=true并回报真实总量(stdout_bytes/stdout_lines)。
error_code | 何时 |
| 缺 |
| 别名解析不出来(回 |
| 握手 / 凭据 / host key(回尝试过的方法与实际指纹) |
| 会话不存在或已被 TTL 回收(回 |
| 传输条目的文件系统情形——按数据返回在条目里,调用本身不是错误 |
| 其它未归类 |
环境变量
都有安全默认值;只有 SSH_MCP_CONFIG 在配置不在默认位时才需要设。
变量 | 默认 | 作用 |
| exe 同级 → cwd | 本地 profile 文件路径 |
|
| 覆盖 ssh_config 路径(测试用) |
|
| known_hosts 路径 |
| — | 密码兜底 |
| 12000 | 握手/认证等待上限 |
| 5000 | 命令超时默认值与上限(只能调小) |
| 600000 | 会话空闲回收 |
| 300000 | 连接池空闲回收 |
开发
bun run lint # = bunx tsc --noEmit;改完 src/** 必跑
bun test # 离线单测,不依赖网络(fake 替身 + 进程内真 SSH 服务器)
bun run live # 对真实主机 27 项端到端验收(读 config.local.json)
bun run sync-skill # 改 SKILL 后同步到技能目录
bun run build # 单文件产物 dist/ssh-mcp.exe
bun run dist-verify # 对产物 13 项验收(--offline 只跑协议层 6 项,CI 用)分层:
src/tools/*只经BridgeCtx(src/bridge.ts)访问连接池/会话,不 import 实现模块。对外契约(工具名、参数集合、错误码、自省模式、ASCII
Keywords:、描述长度上限、SKILL 一致性) 由test/contract.test.ts锁死;改对外面先改它(红),再实现(绿)。docs/domain.md(判据)、test/contract.test.ts(断言)、skills/ssh-mcp/SKILL.md(教学) 是同一结论的三处,改动对外面时三处同改。改完
src/**的远端行为,收官跑一次bun run live;改完产物必须过bun run dist-verify。提交信息用中文 conventional commits;不 push,push 由维护者掌握。
发布
只发 windows-x64 单文件产物,push 驱动:把 package.json 的 version 改一行并提交——
GitHub Actions(.github/workflows/release.yml)在该 commit 创建 v<版本> tag,
跑 lint + 离线测试 + 编译 + dist-verify --offline 自检,把 zip 挂到 Release;版本号没改的 push 整段跳过。
版本号只写在 package.json 一处(代码与契约测试从它读取,tag 由 CI 创建),保证 tag ↔ commit ↔ 二进制对应。
每个 Release 挂两个 zip:ssh-mcp-<版本>-windows-x64.zip(按版本存档)与固定名的稳定直链
ssh-mcp-windows-x64.zip(「永远取最新版」的安装/更新命令用它,见「安装」)。
不发 npm:安装路径以仓库为准(exe 走 Release 直链、SKILL 走 skills CLI),不占也不依赖 npm 包名——
npm 上的 ssh-mcp 名字 2026-11 实测已被另一个项目占用,走 npm 还得改名与发布账号,收益不抵成本。
边界(明确不做)
不做后台任务/job 家族(异步任务表、轮询取结果)——用
nohup … &+ 轮询,原生命令能做。不把 SFTP 的 list/stat/read/write/mkdir 做成工具——远端
ls/stat/sed/cat/mkdir -p更贴近模型既有能力。不做凭据托管类扩展(公钥自动注册、桥代持/代问 sudo 口令、elicitation)——见「凭据约束」。
不启用 ControlMaster,不引入系统 ssh 子进程或 plink 后端;不做 npm 发布 / Docker / Web UI / 遥测。
不读写
~/.ssh/config,不改写私钥;对known_hosts仅追加。
理由展开在 docs/domain.md「明确不做」一节。
License
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Linux VMs for AI agents: create VMs, run commands, edit files and open preview URLs.
Scoped, audited SSH exec, sessions, and SFTP on your saved servers without exposing credentials
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables LLMs to interact with remote servers via SSH, supporting command execution, file upload/download, and directory listing.7MIT
- FlicenseAqualityCmaintenanceEnables LLMs to securely SSH into remote servers, execute commands, and manage files via SFTP including listing, reading, writing, deleting, and renaming files.11-
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to run shell commands over SSH on a fixed, pre-registered set of Linux machines, returning structured results with audit logging, enforced timeouts, output limits, and explicit registry management. It also supports safe file upload/download and multi-host command execution.MIT
- AlicenseBqualityBmaintenanceEnables LLMs and automation agents to securely connect to and operate Linux/Unix hosts over standard OpenSSH, including command execution, interactive PTY sessions, SFTP file management, and dynamic multi-host connection handling. It also includes safety rules that block dangerous commands and truncates large outputs to protect model context.3160 npmApache 2.0