cygnus-ssh-mcp

---

提示

作者的话： 自 2025 年 4 月以来，我一直每天使用它管理十几台机器和设备，以及一台运行着 30 多个容器的 Proxmox 主机；这些设备通过 Tailscale 连接在同一网络中。它最初是为了解决 我自己的问题而开发的，此后为我省去了大量手动工作。一年来，我一直用它管理 Linux 设备， 后来又添加了对 Windows、macOS 以及 BusyBox 等精简 Shell 设备的支持。现在我将它开源， 因为我认为，任何管理真实基础设施的人都会觉得它同样实用。这是一个刚刚公开的仓库， 但它背后的工具并非新鲜事物，也不是未经验证的项目——它已在我自己的服务器上经受了一年多的实战考验。

如果你觉得它有用，点个 ⭐ 星或推荐给管理自己基础设施的人，对这样一个新项目意义重大——谢谢！

---

为什么选择 cygnus-ssh-mcp？

**cygnus-ssh-mcp 是一个 MCP 服务，可用于 Claude Desktop、Claude Code、 OpenCode 或任何其他兼容 MCP 的客户端，能通过 SSH 将你的 AI 助手直接连接到 远程服务，并提供 46 个专用工具，而不是一个通用命令运行器。**它能将自然语言请求转化为实际的系统管理操作——通过别名连接、编辑文件、管理后台进程、处理 sudo——支持 Linux、macOS 和 Windows 目标。

要妥善实现这些功能，就必须解决大量真正棘手、因平台而异的问题，而简单的 ssh 封装根本不必处理这些问题。本项目曾一一遇到并艰难修复，包括：

• 从 Windows 目标获取真实 PID，而不是毫无意义的本地通道编号
• 当 Win32-OpenSSH 悄然将退出码统一变成 1 时，恢复实际退出码
• 通过 SFTP 读取文件内容，而不是使用 Get-Content，因为 PowerShell 控制台会按 OEM 代码页编码 stdout，导致所有非 ASCII 内容损坏
• 终止通过 sudo 启动的后台进程，同时避免遗留孤立的特权子进程，或盲目地向错误的 PID 发送 SIGKILL

只有在真实条件下，实际对 Linux、macOS 和 Windows 目标运行这些工具时，才会遇到这些问题——而这正是本项目发现并解决每一个问题的方式，而不是照着文档猜测。

你将获得	基础 SSH MCP	cygnus-ssh-mcp
运行命令	✅	✅
带别名的预配置主机	❌	✅
Sudo 支持（Linux/macOS）	有限	✅
Windows Server 支持	❌	✅
后台任务管理	❌	✅
按行编辑文件	❌	✅
带输出的命令历史记录	❌	✅
递归目录操作	❌	✅
创建/解压归档文件	❌	✅
完整 Unicode 支持	因情况而异	✅

除了 Linux、macOS 和 Windows，cygnus-ssh-mcp 还可连接到更多设备——路由器、NAS 和其他非标准 SSH 目标也能连接，只需使用 flex 平台类型，并通过能力探测检测每台设备的 Shell 实际支持哪些操作。请参阅下文的连接到其他平台。

警告

**对其他平台（flex）的支持仍在开发中。**该功能已在若干真实设备上验证，但路由器、NAS 和嵌入式系统种类繁多——在尚未测试的硬件上使用时，可能会遇到问题。

Agent 任务示例

让支持 MCP 的 Agent 执行以下任务：

• “检查我的 web 主机上的磁盘空间、内存、运行时间和近期日志。”
• “安全地修补这个远程配置文件，并向我展示差异。”
• “上传这个构建产物，解压后重启服务。”
• “在后台启动这个命令，稍后获取输出。”
• “检查我的 Windows SSH 主机上正在运行的进程。”

---

前置条件：目标服务上的 SSH

cygnus-ssh-mcp 通过标准 SSH 连接——它本身不提供 SSH，因此每台要管理的服务都需要已安装并运行 SSH 服务端。

Linux - 通常已预装在服务器发行版中；如果没有：

sudo apt install openssh-server   # Debian/Ubuntu
sudo systemctl enable --now ssh

macOS - 在“系统设置”→“共享”中启用“远程登录”，或在终端中运行：

sudo systemsetup -setremotelogin on

Windows（Server 2019+ 或 Windows 10/11）- OpenSSH Server 是可选功能：

Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0
Start-Service sshd
Set-Service -Name sshd -StartupType 'Automatic'

有关 Windows Server 2016 和其他特殊情况，请参阅 Windows 支持。

---

安装

从以下两个选项中选择一个——它们是互不关联的工具，不共用存储，因此一个工具执行的命令不会看到或影响另一个工具执行的操作。

选项 A：pip（持久安装）

pip install cygnus-ssh-mcp

卸载或升级：

pip uninstall cygnus-ssh-mcp
pip install --upgrade cygnus-ssh-mcp

选项 B：uvx（完全无需安装）

说明

什么是 uvx？ 它是 uv（一款快速的 Python 包管理器）的一部分——uvx <package> 会将包下载到临时的隔离缓存中并立即运行，而不会将其安装到系统 Python、项目中，也不会安装到 pip 能访问的任何位置。之后无需管理任何残留内容。如果你只想让 MCP 客户端启动此服务，而完全不必考虑 Python 环境，这是最简单的选项。

uvx cygnus-ssh-mcp

无需“卸载”——uvx 每次运行时都会重新解析并获取最新版本。如果要强制重新获取或清除缓存，请改用：

uvx --refresh cygnus-ssh-mcp   # force this run to ignore the cache
uv cache clean                 # clear uv's entire package cache

如果你想使用会持久保留的 uvx 风格设置（这样就不必每次都重新获取），并且可以按需升级，请改用 uv tool install cygnus-ssh-mcp——使用 uv tool uninstall cygnus-ssh-mcp / uv tool upgrade cygnus-ssh-mcp 管理。它仍然与 pip（选项 A）分开——不要混用 pip 命令和通过 uv/uvx 设置的内容，它们彼此不可见。

---

快速开始

1. 添加主机

无需手动创建任何文件——服务首次启动时，如果尚无主机配置文件，就会自动在 ~/.mcp_ssh_hosts.toml 创建一个空文件（权限为安全的 0o600）。只需打开该文件（或在 AI 助手中使用 ssh_conn_add_host），然后添加类似以下内容的条目：

# Minimal (password auth) - only required fields
["[email protected]"]
password = "your_password"
port = 22

# With alias and sudo (most common setup)
["[email protected]"]
password = "your_password"
port = 22
sudo_password = "sudo_pass"        # optional: for use_sudo operations
alias = "prod"                     # optional: connect by alias
description = "Production server"  # optional: for documentation

# SSH key authentication
["[email protected]"]
keyfile = "~/.ssh/id_ed25519"
port = 22
alias = "staging"

# Windows Server (requires OpenSSH)
["[email protected]"]
password = "your_password"
port = 22
alias = "win-prod"

必填字段： port +（password 或 keyfile） 可选字段： alias、description、sudo_password、key_passphrase

如果你的账户使用密码认证，sudo_password 为可选项——未指定时，use_sudo 操作也会复用常规的 password。只有当你的 sudo 密码与登录密码不同时，或使用 SSH 密钥认证（keyfile）且完全未设置 password 字段时，才需要此字段——在这种情况下，请显式设置 sudo_password，或在服务器上配置免密码 sudo。

提示

主机文件位置： 默认位置为 ~/.mcp_ssh_hosts.toml。如果未找到，则回退到 ./mcp_ssh_hosts.toml。 使用 --config /path/to/hosts.toml 指定自定义位置。如果所用路径下已存在文件，则绝不会覆盖或重置该文件——只有在文件尚不存在时才会自动创建。

警告

注意隐藏的文件扩展名。 如果你在记事本或 TextEdit 中自行创建此文件，Windows 和 macOS 默认都会隐藏已知扩展名——你命名为 mcp_ssh_hosts.toml 的文件，实际上可能会被悄悄保存为 mcp_ssh_hosts.toml.txt，导致服务始终无法找到它。在资源管理器/Finder 中启用“显示文件扩展名”，或在终端中检查： ls -la ~/.mcp_ssh_hosts.toml*（macOS/Linux）或 dir %USERPROFILE%\.mcp_ssh_hosts.toml*（Windows）——两者都应只显示一个文件，且 .toml 后没有多余的扩展名。

2. 添加到 MCP 客户端

大多数 MCP 客户端（Claude Desktop、Claude Code、OpenCode、Cursor、Cline、Windsurf 等）都使用下方所示的相同 mcpServers JSON 结构，只有配置文件的名称和位置因客户端 而异。这里以 Claude Desktop 为具体示例；有关一种有所不同的客户端，请参阅下文的 Claude Code 说明，或者查阅你所用客户端的文档，了解其配置文件路径。

警告

要使 "command": "cygnus-ssh-mcp"（如下所示）正常工作，Python 必须位于 PATH 中。 这是 MCP 客户端无法启动服务（或工具列表始终不显示）的最常见原因；而且 Python 往往安装在同一台机器上的多个不同位置，因此很容易遇到这个问题。请先运行以下命令检查：

python --version   # Windows/macOS/Linux
python3 --version  # macOS/Linux，如果未找到上面的命令

如果命令失败并显示“not recognized”/“command not found”，则说明 Python 不在 PATH 中——请先修复（在 Windows 上重新安装 Python，并勾选“Add to PATH”；或者将其添加到 shell 配置文件中），或者直接查找已安装可执行文件的完整路径来绕过此问题：运行 where cygnus-ssh-mcp（Windows）或 which cygnus-ssh-mcp（macOS/Linux），然后将其直接用作 command：

{
  "mcpServers": {
    "ssh": {
      "command": "C:\\Users\\yourname\\AppData\\Local\\Programs\\Python\\Python312\\Scripts\\cygnus-ssh-mcp.exe",
      "args": ["--config", "C:\\Users\\yourname\\.mcp_ssh_hosts.toml"]
    }
  }
}

对于 Claude Desktop，请编辑 claude_desktop_config.json：

{
  "mcpServers": {
    "ssh": {
      "command": "cygnus-ssh-mcp"
    }
  }
}

或者使用自定义主机文件位置：

{
  "mcpServers": {
    "ssh": {
      "command": "cygnus-ssh-mcp",
      "args": ["--config", "/path/to/my_hosts.toml"]
    }
  }
}

在 Windows 上，请使用带有转义反斜杠的绝对路径（JSON 需要 \\，而不是 单个 \）：

{
  "mcpServers": {
    "ssh": {
      "command": "cygnus-ssh-mcp",
      "args": ["--config", "C:\\Users\\yourname\\.mcp_ssh_hosts.toml"]
    }
  }
}

使用 Claude Code 而不是 Claude Desktop？ 它读取的是项目级 .mcp.json 文件（位于项目根目录中），而不是 claude_desktop_config.json；它的架构还支持几个 Desktop 不具备的额外字段：

{
  "mcpServers": {
    "cygnus_ssh": {
      "command": "cygnus-ssh-mcp",
      "args": ["--config", "/path/to/.mcp_ssh_hosts.toml"],
      "working_dir": "/path/to/your/project",
      "auto_start": true
    }
  }
}

• working_dir - 服务进程运行的目录。Claude Desktop 没有对应选项——它完全 不提供可配置的工作目录，这正是上面的 Desktop 示例始终使用绝对路径的原因。
• auto_start - Claude Code 是否自动启动此服务。Claude Desktop 始终自动启动 所有已配置的服务；没有相应的开关。

其他所有内容——--config 参数，以及上方警告中的 PATH/反斜杠注意事项——对这两个 客户端都同样适用。

3. 开始管理服务器

说明

以下示例中的 PROD 只是一个示例别名（步骤 1 的主机文件中设置了 alias = "prod"），并非特殊名称。如果主机未配置别名，请使用完整的 user@host 键来指代它，例如：“连接到 [email protected] 并……”或“连接到 [email protected] 并……”。

根据你使用的大模型/客户端，它可能不会自动意识到应该调用此 MCP 服务；如果它尝试不连接就回答，或声称无法访问远程服务器，请明确告诉它使用 SSH MCP 工具（例如：“使用 SSH MCP 连接到 PROD 并……”）。

只需这样说：

“连接到 PROD，告诉我这台机器的情况——硬件、状态，以及所有其他信息”

“连接到 GPU 服务器，告诉我它有多少块显卡，以及总 VRAM 有多少”

“编辑 /etc/nginx/nginx.conf，将 worker_connections 改为 2048”

“查找 /var/log 中所有大于 100MB 的 .log 文件”

它也能轻松处理多步骤任务——安装软件包、编辑配置、开放防火墙端口并重启服务，只需一次请求：

“安装 PostgreSQL，将其设置为监听所有网络接口，在 pg_hba.conf 中添加一条允许远程连接的规则，在防火墙中开放 5432 端口，并创建一个名为 analytics 的数据库”

“搭建完整的 LAMP 堆栈，下载最新版 WordPress，使用新的数据库配置 wp-config.php，并让网站在 /var/www/wordpress 上运行”

“为 example.com 获取 Let's Encrypt 证书，配置 nginx 通过 HTTPS 提供服务，并将所有 HTTP 流量重定向到 HTTPS”

“我的 Node 应用在 /opt/api 中不断崩溃——检查日志，找出原因，并将其设置为会自动重启的 systemd 服务”

“审计 PROD 的安全性——检查开放了哪些端口、哪些服务实际在监听这些端口、防火墙规则是否匹配，并标记任何看起来不应暴露在互联网上的内容”

---

平台支持

cygnus-ssh-mcp 可从任意客户端（Windows、Linux、macOS）连接到任意目标服务器：

来源（客户端）	目标（服务器）	状态
Windows	Linux	✅ 已测试
Windows	Windows	✅ 已测试
Linux	Linux	✅ 已测试
Linux	Windows	✅ 已测试
macOS	任意	✅ 支持

Windows 目标需要安装并运行 OpenSSH Server。

---

连接到其他平台

警告

此功能仍在开发中。 已在下方列出的若干真实设备上验证，但路由器、NAS 和嵌入式系统差异极大——可能会遇到尚不支持的设备；如果遇到，请提交 issue。

除了 Linux、macOS 和 Windows，cygnus-ssh-mcp 还能连接到任何能够响应基本 shell 命令的 SSH 目标，包括路由器、NAS 设备、BSD 内核设备及其他嵌入式 Linux 设备。这些设备的 os_type 会报告为 "flex"。

连接时，会执行一次性功能探测，检查本项目工具所依赖的特定 shell/coreutils 功能（GNU find -printf、stat -c、du -sb、tar --strip-components、ps -o pgid=、xargs -0 等）——许多基于嵌入式系统或 BusyBox 的设备支持的选项比完整 GNU coreutils 少。探测结果会通过 ssh_conn_connect 返回，字段为 capabilities；如果有功能缺失，还会返回 capability_warnings。需要缺失功能的工具会报出明确错误，准确指出不可用的功能，并在有可行替代方案时给出具体选项——不会静默降级。如果存在可移植的替代方案（例如不依赖 GNU find -printf 的 glob 搜索和目录大小查询），工具会直接使用该方案。

探测还会检查 SFTP 是否可用：有些设备完全没有 SFTP（OpenWrt），有些设备提供的 SFTP 所显示的文件系统与 shell 不同（Synology DSM 的 SFTP 仅显示共享文件夹）。无论哪种情况，基于 SFTP 的文件工具都会说明这一点，并指向 ssh_cmd_run，而不是返回错误结果。

已验证设备（每台设备均通过自动化测试套件验证；该套件会执行日常管理工作流，并将每个工具的结果与 shell 进行核对）：

设备	结果
Alpine Linux（BusyBox）	以 linux 身份连接；默认没有 bash、sudo、GNU find -printf 或 ps -o pgid=——依赖这些功能的工具会报出明确错误并提供替代方案，其他功能均可使用
OpenWrt	以 linux 身份连接；仅限 root 用户，没有 SFTP，且大多数 GNU 扩展都不可用——基于 shell 的工具可用，文件操作通过 ssh_cmd_run 进行
FreeBSD	以 flex 身份连接；默认没有 bash，sudo/任务工具已调整为使用 sh
Synology DSM（NAS）	以 linux 身份连接；提供完整 GNU coreutils 和 sudo，但其 SFTP 仅显示共享文件夹，因此基于 SFTP 的文件工具已禁用，文件操作通过 ssh_cmd_run 进行

已知限制： 有些设备会完全禁止某个账号通过 SSH 访问 shell，即使该账号拥有管理员级权限也是如此——这种情况下，登录成功后所有命令（即使是单独的 echo）都会立即失败。功能探测无法解决此问题；发生这种故障时，ssh_conn_connect 会说明具体情况，而不是返回通用错误。

完整详情、功能列表和当前限制： docs/26-alternate-platforms.md。

---

功能

主机配置

无需再输入凭据。使用别名连接。

["[email protected]"]
password = "secret"
port = 22
alias = "web"

然后只需说：“连接到 WEB”

支持密码、SSH 密钥和带密码短语的加密密钥。

无需影响其他字段，即可更新现有主机的某个字段（ssh_host_update）；也可以在当前会话中让所有主机工具切换到备用配置文件（ssh_host_use_config）——便于按项目或环境分别管理主机列表。

---

按行编辑文件

精确编辑配置文件——无需下载或上传。

# Replace a single line
ssh_file_replace_line(
    file_path="/etc/nginx/nginx.conf",
    match_line="worker_connections 1024;",
    new_line="worker_connections 4096;"
)

# Insert lines after a match
ssh_file_insert_lines_after_match(
    file_path="/etc/hosts",
    match_line="# Custom entries",
    lines_to_insert=["192.168.1.10 app.local", "192.168.1.11 db.local"]
)

内置安全机制：如果匹配项不唯一，操作就会失败——避免意外批量修改。

---

后台任务管理

启动长时间运行的进程，稍后再回来查看。

# Start a backup (returns immediately)
ssh_task_launch(command="./backup.sh", stdout_log="/var/log/backup.log")

# Check status anytime
ssh_task_status(pid=12345)  # → 'running' or 'exited'

# Kill if needed
ssh_task_kill(pid=12345, force=True)

---

全面支持 Sudo

每个工具都支持 use_sudo。密码会自动处理。

ssh_file_write(file_path="/etc/app/config.yaml", content="...", use_sudo=True)
ssh_dir_mkdir(path="/opt/myapp", use_sudo=True)
ssh_archive_extract(archive_path="/backup.tar.gz", destination_path="/", use_sudo=True)

---

三段式超时系统

既不会卡在挂起的命令上，也不会丢失长时间运行的命令状态。

ssh_cmd_run(
    command="./long_script.sh",
    io_timeout=60.0,        # Check back in if silent for 60s (does NOT kill it)
    wait_timeout=20.0,      # Or check back in every 20s regardless of activity
    runtime_timeout=3600.0  # Hard safety cap - the only one that actually kills it
)

io_timeout 和 wait_timeout 不会终止远程命令，而是交由后台监控，以便你稍后查看状态（ssh_cmd_check_status）、读取截至目前收集的输出（ssh_cmd_output），或决定提前结束命令（ssh_cmd_kill）。只有 runtime_timeout 会终止命令。

单次调用的阻塞时间绝不会超过 50 秒（--max-wait / MCP_SSH_MAX_WAIT），因为许多 MCP 客户端（例如 OpenCode）会在 60 秒时中止工具调用，导致交接丢失。运行时间更长的命令只会正常返回 wait_timeout 交接结果，并将 wait_capped: true 设为真——你可以轮询状态，或对需要运行数分钟的任务使用 ssh_task_launch。

---

完整的 Unicode 支持

在所有平台上读写含有表情符号、国际文字和特殊字符的文件。

✅ ❌ 🎉 • → ≥ ∞ │ ┌ ─ 你好 مرحبا Привет café naïve

工作原理：ssh_file_read 和 ssh_file_write 使用 SFTP 直接传输二进制数据，完全绕过 Shell 编码问题。因此，即使目标是 Windows，Unicode 也能完美运行；在 Windows 上，PowerShell 的控制台编码通常会破坏特殊字符。服务端自身的 PowerShell 脚本也会写入 UTF-8，因此 Windows 结果中的文件名（删除预览、Glob 搜索、列表）会保持原样。行编辑会保留文件自身的换行符（CRLF 仍为 CRLF）。

---

Windows 服务端支持

全面支持使用 OpenSSH Server 的 Windows 目标：

• PowerShell 和 CMD 命令执行
• Windows 路径处理（反斜杠、驱动器号、UNC 路径）
• 管理员检测——显示会话是否拥有提升的权限
• 基于 SFTP 的文件操作——安全支持 Unicode，不存在编码问题

注意：在 Windows 上，use_sudo 会被忽略（Windows 没有对应的 sudo）。如需执行提升权限的操作，请使用 Administrator 账户连接。

---

还有更多功能……

• 命令历史记录，支持保留输出和模式筛选
• 递归目录操作：搜索、复制、删除，支持试运行
• 归档操作：创建和解压 tar.gz
• 系统信息：操作系统版本、内存、磁盘、CPU、运行时间
• 模式搜索：在文件中搜索正则表达式和纯文本
• 备用主机配置文件：无需重启，即可按项目或环境切换主机列表

---

全部 46 个工具

连接与主机管理（12 个工具）

工具	描述
ssh_conn_connect	使用预配置的主机连接（按键或别名）
ssh_conn_is_connected	检查 SSH 连接是否处于活动状态
ssh_conn_status	获取连接状态（用户、主机、操作系统、当前工作目录）
ssh_conn_host_info	获取详细的系统信息
ssh_conn_verify_sudo	验证 sudo 访问权限
ssh_conn_add_host	向配置中添加新主机
ssh_host_list	列出所有已配置的主机
ssh_host_update	原地更新现有主机的字段（轮换密码、更改端口等）
ssh_host_remove	从配置中移除主机
ssh_host_use_config	为当前会话切换到备用主机配置文件
ssh_host_disconnect	断开当前会话
list_tools	列出所有可用工具

命令执行（6 个工具）

工具	描述
ssh_cmd_run	执行命令，支持 I/O、等待和运行时超时
ssh_cmd_kill	终止正在运行的命令
ssh_cmd_check_status	检查命令状态
ssh_cmd_output	获取命令输出
ssh_cmd_history	获取命令历史记录并进行筛选
ssh_cmd_clear_history	清除命令历史记录

后台任务（3 个工具）

工具	描述
ssh_task_launch	在后台启动命令
ssh_task_status	检查任务是否正在运行
ssh_task_kill	向任务发送信号

文件操作（12 个工具）

工具	描述
ssh_file_stat	获取文件元数据
ssh_file_read	通过 SFTP 读取文件内容（支持 Unicode）
ssh_file_write	创建／覆盖／追加文件
ssh_file_copy	复制文件
ssh_file_move	移动或重命名文件
ssh_file_transfer	上传或下载文件
ssh_file_find_lines_with_pattern	在文件中搜索模式
ssh_file_get_context_around_line	获取匹配项的上下文
ssh_file_replace_line	替换单行
ssh_file_replace_line_multi	替换为多行
ssh_file_insert_lines_after_match	在匹配项后插入行
ssh_file_delete_line_by_content	按内容删除行

目录操作（11 个工具）

工具	描述
ssh_dir_mkdir	创建目录
ssh_dir_remove	移除目录
ssh_dir_list_files_basic	基本目录列表
ssh_dir_list_advanced	递归列出内容及元数据
ssh_dir_search_glob	按模式搜索文件
ssh_dir_search_files_content	在文件中搜索文本
ssh_dir_calc_size	计算目录大小
ssh_dir_delete	删除并支持试运行
ssh_dir_batch_delete_files	按模式批量删除
ssh_dir_copy	递归复制目录
ssh_dir_transfer	上传或下载整个目录（基于归档）

归档操作（2 个工具）

工具	描述
ssh_archive_create	创建 tar.gz 归档
ssh_archive_extract	解压归档

---

文档

完整文档网站：cygnussystems.github.io/cygnus-ssh-mcp — 支持搜索并提供导航。也可以直接浏览 docs/ 中的原始文件：

• 概览
• 安装
• 平台兼容性
• Windows 支持
• 其他平台（flex）
• 主机配置
• 工具参考
• 命令执行
• 进程管理
• 日志记录
• Claude Desktop 设置

---

使用场景

• DevOps 自动化 — 通过 AI 部署、配置和管理服务
• 日志分析 — 跨多台服务搜索和分析日志
• 配置管理 — 通过精确的行操作编辑配置文件
• 备份与恢复 — 创建归档、传输文件、还原备份
• 系统监控 — 检查状态、验证服务、监控进程
• 安全审计 — 搜索敏感模式、验证配置

---

许可证

GPL-3.0 — 免费且开源。

---