ssh-mcp-server 是一个 SSH MCP 服务器，为 AI 智能体提供远程服务器操作工具，作者通过 OpenSSH 完成远程命令执行、文件传输、日志搜索与服务器审计。其定位是节省调试、开发和服务器维护的时间与 token。
主要能力与特点：
- 复用本机 OpenSSH 客户端：使用你已有的密钥、~/.ssh/config、跳板机（jump hosts）和代理转发，不捆绑 SSH 实现、无需编译、无原生绑定；支持时每个目标共享一个多路复用连接，认证一次而非每条命令一次。
- 兼容现代与老旧设备：现代服务器、旧版路由器、NAS 等均可使用。对旧协议自动回退（如现代 scp 被拒绝时改用旧协议并记住该机器）；缺失现代功能时会走旧路径。
- 面向 MCP 生态：基于官方 MCP SDK，全程 TypeScript，拥有 2500+ 单元测试以及针对真实容器运行的实际环境测试套件。兼容 Claude Code、Codex CLI、Cline、opencode、Gemini CLI、Qwen Code、Hermes 等 MCP 客户端。
- 与裸 SSH 的差异：原始 shell 会给智能体大量噪声输出（重复命令、ASCII 表格、日志转储），消耗 token；专用工具批量执行例行检查、限制嘈杂输出并返回关键部分，降低 token 成本，减少智能体猜测与幻觉，提高修复准确性。示例中，真实排障会话把 49 次独立命令调用减少到 4 次 MCP 调用；ssh_audit_baseline 可一次批量检查系统、磁盘、内存、端口、sshd、失败单元、Docker、防火墙与更新，结果以 CRITICAL / WARNING / OK 标注，未测量部分会明确说明而非默认为零。
使用方式与安装：
- 无需全局安装，npx 首次使用即下载包。将其添加到 MCP 客户端（如 Claude Code），可为每个项目配置；也可手写配置，多数客户端共享相同服务器配置形态。
- 需创建 ~/.claude/ssh-profiles.json，至少包含一台机器即可连接。Codex、opencode、Qwen Code 等客户端配置见项目文档。
- 也可作为插件安装：部分客户端（如 Claude Code）可整个作为插件使用，插件读取 ~/.claude/ssh-profiles.json（除非 SSH_PROFILES_FILE 指定其他文件），因此需先创建该文件。
- 运行要求：Node.js 18+，系统 ssh 客户端在 PATH 中。Windows 上使用基于密钥的配置；当前不支持密码和口令短语配置。
- 如需固定版本、离线工作或减少每次启动的注册表检查，可执行 npm install -g @hypnosis/ssh-mcp-server，然后使用 ssh-mcp-server 作为命令替代 npx。
主要工具（共 18 个 SSH MCP 工具，完整参数见 docs/tools.md）：
- 运行 SSH 命令、管理远程文件：命令、文件读写、目录列表，每条结果已解析。
- 监控长时间运行的 SSH 任务：慢任务被分离并跟踪，每次查看都会报告进度；任务状态保存在远端磁盘，可区分 running / finished / lost，支持从上次字节偏移继续读取输出，并可向整个进程组发送信号。
- 搜索日志与检查服务器健康：支持文件与容器日志搜索，一次性获取机器全景；输出受限，避免日志尾部占满上下文。
- 通过 SSH 上传下载文件：二进制安全的传输与完整性校验；二进制与大文件应使用 ssh_upload / ssh_download，base64 分块与 heredoc 不具备二进制安全或原子性。
- 远程配置安全编辑：带 verified 结果，可能为 verified、unavailable（服务器无哈希工具）或 skipped（未请求校验）；读取可用 ssh_file_read 接受路径列表，ssh_file_list 支持通配、递归、大小与权限。
- 批量带 sudo 命令：每条命令有独立 stdout 与 stderr；运行但无输出为空字符串，未运行则无该字段；单条命令输出超过 128 KB 时保留头尾并在中间标注截断位置与 clipped_bytes，按字节边界切割并回退到字符边界，避免出现替换字符。sudo 密码通过标准输入传递，来自配置的 sudoPassword 或 password；读取自身标准输入的命令不会获得密码。
- 破坏性命令保护：守卫在本地、命令到达 SSH 之前运行，区分可恢复操作与破坏数据容器的操作，并检查链式与批量命令中的顺序。错误顺序（如先删目录后备份）会被拦截；docker compose down -v、递归删除文件系统根/home/系统目录（包括符号链接指向处）、未解析目标（如 rm -rf "$DIR"/*）均被拒绝；以模式匹配命令行的情况会改写或按编号执行。三种结果保持区分：找到目标、展开无结果、无法询问；后两种同样是拒绝。已审查命令可加 # CONFIRMED-DESTRUCTIVE 放行；批量中一项被拒则整批停止。该守卫仅在单次调用内工作，不能跨调用关联删除与读取，也不理解未知工具，属于安全带而非策略引擎。路径限制与引用规则见 docs/security.md。
MCP 工具安全标注：标准 MCP 标注告知客户端工具是只读、破坏性、幂等还是开放世界，完整表见文档。
适用人群：希望更快审计、事件检查与日常服务器操作的 DevOps 与 SRE；使用 AI 助手开发并在自有服务器运行的独立开发者；希望获得结构化工具而非无限制裸 shell 的系统管理员与平台工程师；没有专职运维团队、自运行 VPS 的开发者与小团队；拥有仍可用的老式硬件（homelab、NAS、路由器）的用户。
限制与注意事项：需要 Node.js 18+ 与系统 ssh 客户端；Windows 仅支持基于密钥的配置；破坏性命令守卫不跨调用、不识别未知工具；部分旧设备缺少哈希工具时会返回 unavailable 而非校验通过；资料未提供具体的收费、价格或平台信息。
