cygnus-ssh-mcp 是一个 MCP 服务器，用于通过 SSH 远程管理服务器，并让 AI 智能体对 Linux、macOS、Windows 目标执行真实系统管理操作。它面向 Claude Desktop、Claude Code、OpenCode 或任何兼容 MCP 的客户端，提供 46 个专用工具，而不是一个通用的命令执行器。作者表示自 2025 年 4 月起几乎每天使用它管理十几台机器与设备，以及一台运行 30 多个容器的 Proxmox 主机，网络通过 Tailscale 连接；项目最初为解决自身问题而开发，现已开源。
主要能力
- 将自然语言请求转为系统管理操作：按别名连接、行级编辑文件、管理后台进程、处理 sudo，覆盖 Linux、macOS、Windows 目标。
- 跨平台 SSH 管理，并为真机场景解决多项平台难题：从 Windows 目标获取真实 PID；在 Win32-OpenSSH 把退出码压成 1 时恢复实际退出码；通过 SFTP 读取文件内容而不是 Get-Content，避免 PowerShell 控制台以 OEM 代码页编码 stdout 损坏非 ASCII 内容；在终止 sudo 启动的后台进程时，避免留下特权子进程或对错误 PID 盲目发送 SIGKILL。
- 支持 Linux、macOS、Windows 之外的 SSH 目标：路由器、NAS、BSD 内核设备及其他嵌入式 Linux 设备可通过 flex 平台类型与能力探测接入。
- 按别名连接主机，支持 password、SSH key、带 passphrase 的加密密钥。
- 行级文件编辑：无需下载或上传即可进行精细修改；若匹配不唯一则操作失败，避免意外批量编辑。
- 后台任务管理：启动长时间运行的进程并稍后检查。
- 全面 sudo 支持：所有工具均支持 use_sudo，密码自动处理。
- 三向超时系统：io_timeout 和 wait_timeout 不会终止远程命令，而是转为后台监控，以便稍后通过 ssh_cmd_check_status 检查。
使用方式
前提：目标服务器需已安装并运行 SSH 服务器。cygnus-ssh-mcp 通过标准 SSH 连接，本身不提供 SSH。
Linux 服务器发行版通常预装 SSH；macOS 可在系统偏好设置 → 共享中启用“远程登录”，或从终端操作；Windows（Server 2019+ 或 Windows 10/11）的 OpenSSH Server 是可选功能。Windows Server 2016 及其他边缘情况参见 Windows Support。
安装有两种独立选项，不共享存储，互不可见：
- 选项 A：pip 持久安装。卸载或升级也通过 pip 管理。
- 选项 B：uvx 无需安装。uvx 是 uv（快速 Python 包管理器）的一部分，uvx <package> 会把包下载到一次性隔离缓存并立即运行，不安装到系统 Python、项目或 pip 可见的位置，运行后不留需要管理的东西。uvx 每次运行都会重新解析并获取最新版本；如需强制重新获取或清除缓存有对应命令。若想要持久且可主动升级的 uvx 式安装，可用 uv tool install cygnus-ssh-mcp，并通过 uv tool uninstall / uv tool upgrade 管理；它仍与 pip 选项分离，不要混用命令。
添加主机：服务器首次启动时会自动在 ~/.mcp_ssh_hosts.toml 创建空主机配置文件（0o600 权限），无需手工创建。可在该文件或用 AI 助手内的 ssh_conn_add_host 添加条目。必填字段为 port +（password 或 keyfile）；可选字段为 alias、description、sudo_password、key_passphrase。若账户使用密码认证，sudo_password 可省略，此时 use_sudo 操作复用常规密码；仅当 sudo 密码与登录密码不同，或使用 keyfile 且没有 password 字段时需要显式设置 sudo_password，或在服务器上配置免密码 sudo。主机文件默认位置为 ~/.mcp_ssh_hosts.toml，找不到时回退到 ./mcp_ssh_hosts.toml，可用 --config /path/to/hosts.toml 指定自定义路径；若文件已存在，绝不会被覆盖或重置。注意隐藏文件扩展名：用记事本或文本编辑自己创建时可能被保存为 mcp_ssh_hosts.toml.txt，导致服务器找不到；应开启显示文件扩展名，或在终端确认。
添加到 MCP 客户端：多数 MCP 客户端使用相同的 mcpServers JSON 结构，仅配置文件名称和位置不同。Claude Desktop 的示例编辑 claude_desktop_config.json，也可指定自定义主机文件位置；Windows 需使用绝对路径并转义反斜杠。使用 Claude Code 时读取项目根目录的 .mcp.json，其 schema 还支持 working_dir 和 auto_start 两个字段；--config 参数与 PATH/反斜杠注意事项同样适用。
Python 必须在 PATH 中，否则 "command": "cygnus-ssh-mcp" 无法工作，这是 MCP 客户端启动失败的常见原因。可先用命令检查；若报“找不到”，则修复 PATH，或查找可执行文件完整路径并直接作为 command 使用。
开始管理服务器：示例中的 PROD 只是别名示例，不是特殊名称。若主机未配置别名，用完整 user@host 指代，例如“Connect to admin@203.0.113.10 and...”或“Connect to deploy@myserver.example.com and...”。根据 LLM/客户端不同，可能不会自动使用该 MCP 服务器；若它未连接就作答或称无法访问远程服务器，可明确要求使用 SSH MCP 工具。
适用场景
文档给出的示例任务包括：检查磁盘空间、内存、运行时间和近期日志；安全修补远程配置文件并显示 diff；上传构建产物、解压并重启服务；后台启动命令并稍后获取输出；检查 Windows SSH 主机上的运行进程。也支持多步骤任务，例如安装 PostgreSQL 并配置监听、pg_hba.conf 规则、防火墙端口与数据库；搭建 LAMP 栈并配置 WordPress；获取 Let's Encrypt 证书并配置 nginx HTTPS 与 HTTP 重定向；排查 Node 应用崩溃并配置 systemd 自重启；审计暴露端口、监听情况、防火墙规则并标记不应对外暴露的内容。
平台支持与限制
cygnus-ssh-mcp 可从任何客户端（Windows、Linux、macOS）连接任何目标服务器；Windows 目标需要安装并运行 OpenSSH Server。
接入备用平台（flex）目前是进行中功能，已在若干真实设备上验证，但路由器/NAS/嵌入式系统差异极大，可能遇到尚不支持的设备。除 Linux、macOS、Windows 外，能响应基本 shell 命令的 SSH 目标会报告 os_type: "flex"。连接时会执行一次性能力探测，检查工具依赖的特定 shell/coreutils 功能（如 GNU find -printf、stat -c、du -sb、tar --strip-components、ps -o pgid=、xargs -0 等），许多嵌入式/BusyBox 设备只支持较少的标志集。结果通过 ssh_conn_connect 返回 capabilities 与 capability_warnings；缺少能力时工具会给出明确错误并指出不可用的具体项，存在替代方案时还会给出具体回退，不会静默降级。若存在可移植替代（如不依赖 GNU find -printf 的 glob 搜索和目录大小），工具会直接使用。探测还检查 SFTP 是否可用：有些设备没有 SFTP（如 OpenWrt），有些 SFTP 显示的文件系统与 shell 不同（如 Synology DSM 仅共享的 SFTP）；基于 SFTP 的文件工具会说明情况并指向 ssh_cmd_run，而不是给出错误答案。已知限制：某些设备会完全拒绝某账户的 SSH shell 访问，即使该账户有管理员权限，表现为登录成功后所有命令（包括裸 echo）立即失败；能力探测无法解决，ssh_conn_connect 会在失败中说明情况，而非泛泛报错。完整细节、能力列表和当前缺口见 docs/26-alternate-platforms.md。
主机配置支持别名连接，并可通过 ssh_host_update 更新现有主机的单个字段而不丢失其余字段，或通过 ssh_host_use_config 为会话切换所有主机工具到备用配置文件，便于按项目或环境维护独立主机列表。
关于收费、价格、具体安装命令及代码内容，资料中未完整提供，暂未提供。
