cygnus-ssh-mcp

cygnus-ssh-mcp is an MCP server for remotely managing servers over SSH and enabling AI agents to perform real system administration operations on Linux, macOS, and Windows targets. It is aimed at Claude Desktop, Claude Code, OpenCode, or any MCP-compatible client, providing 46 dedicated tools rather than a generic command executor. The author states that since April 2025 he has used it almost daily to manage a dozen machines and devices, as well as a Proxmox host running more than 30 containers, with the network connected via Tailscale; the project was originally developed to solve his own problems and has now been open-sourced.

Main capabilities

• Turn natural language requests into system administration operations: connect by alias, edit files line by line, manage background processes, handle sudo, covering Linux, macOS, and Windows targets.
• Cross-platform SSH management, solving several platform challenges for real-machine scenarios: obtaining the real PID from Windows targets; recovering the actual exit code when Win32-OpenSSH collapses it to 1; reading file contents via SFTP instead of Get-Content, avoiding corruption of non-ASCII content when the PowerShell console encodes stdout with the OEM code page; and when terminating background processes started by sudo, avoiding leaving privileged child processes behind or blindly sending SIGKILL to the wrong PID.
• Support SSH targets beyond Linux, macOS, and Windows: routers, NAS devices, BSD-kernel devices, and other embedded Linux devices can be connected through the flex platform type and capability probing.
• Connect to hosts by alias, supporting password, SSH key, and encrypted keys with a passphrase.
• Line-level file editing: fine-grained modifications without downloading or uploading; if the match is not unique, the operation fails, avoiding accidental bulk edits.
• Background task management: start long-running processes and check on them later.
• Comprehensive sudo support: all tools support use_sudo, with automatic password handling.
• Three-way timeout system: io_timeout and wait_timeout do not terminate the remote command, but instead switch to background monitoring so it can be checked later via ssh_cmd_check_status.

UsageApproach

Prerequisite: The target server must already have an SSH server installed and running. cygnus-ssh-mcp connects via standard SSH and does not provide SSH itself.

Linux server distributions usually come with SSH preinstalled; on macOS you can enable "Remote Login" in System Preferences → Sharing, or do it from the terminal; on Windows (Server 2019+ or Windows 10/11), OpenSSH Server is an optional feature. For Windows Server 2016 and other edge cases, see Windows Support.

There are two independent installation options that do not share storage and are invisible to each other:

• Option A: pip persistent installation. Uninstallation or upgrades are also managed via pip.
• Option B: uvx with no installation required. uvx is part of uv (a fast Python package manager); uvx <package> downloads the package into a one-off isolated cache and runs it immediately, without installing it into the system Python, the project, or any location visible to pip, and leaves nothing behind that needs managing after it runs. uvx re-resolves and fetches the latest version on every run; there are corresponding commands if you need to force a re-fetch or clear the cache. If you want a persistent, proactively upgradable uvx-style installation, you can use uv tool install cygnus-ssh-mcp and manage it via uv tool uninstall / uv tool upgrade; it remains separate from the pip option, so do not mix commands.

Adding hosts: On first startup, the server automatically creates an empty host configuration file at ~/.mcp_ssh_hosts.toml (with 0o600 permissions), so there is no need to create it manually. You can add entries in that file or use ssh_conn_add_host within the AI assistant. Required fields are port + (password or keyfile); optional fields are alias, description, sudo_password, key_passphrase. If the account uses password authentication, sudo_password can be omitted, in which case use_sudo operations reuse the regular password; you only need to set sudo_password explicitly when the sudo password differs from the login password, or when using a keyfile and there is no password field, or configure passwordless sudo on the server. The host file's default locationSet to ~/.mcp_ssh_hosts.toml, falling back to ./mcp_ssh_hosts.toml when not found; a custom path can be specified with --config /path/to/hosts.toml; if the file already exists, it will never be overwritten or reset. Note the hidden file extension: when creating it yourself with Notepad or a text editor, it may be saved as mcp_ssh_hosts.toml.txt, causing the server to not find it; you should enable showing file extensions, or confirm in the terminal.

Adding to an MCP client: most MCP clients use the same mcpServers JSON structure, with only the configuration file name and location differing. For Claude Desktop, the example edits claude_desktop_config.json, and a custom hosts file location can also be specified; on Windows, absolute paths must be used and backslashes escaped. When using Claude Code, it reads .mcp.json in the project root directory, and its schema also supports the two fields working_dir and auto_start; the --config parameter and the PATH/backslash caveats also apply.

Python must be in PATH, otherwise "command": "cygnus-ssh-mcp" will not work, which is a common cause of MCP client startup failure. You can check first with a command; if it reports "not found", then fix PATH, or find the full path to the executable and use it directly as command.

Start managing servers: PROD in the examples is just an alias example, not a special name. If a host has no alias configured, refer to it with the full user@host, for example "Connect to admin@203.0.113.10 and..." or "Connect to deploy@myserver.example.com and...". Depending on the LLM/client, it may not automatically use this MCP server; if it answers without connecting or says it cannot access the remote server, you can explicitly ask it to use the SSH MCP tool.

Applicable scenarios

The example tasks given in the documentation include: checking disk space, memory, uptime, and recent logs; safely patching remote configuration files and showing the diff; uploading build artifacts, extracting them, and restarting services; starting a command in the background and retrieving its output later; checking a Windows SSH hostrunning processes on it. It also supports multi-step tasks, such as installing PostgreSQL and configuring listening, pg_hba.conf rules, firewall ports, and the database; setting up a LAMP stack and configuring WordPress; obtaining a Let's Encrypt certificate and configuring nginx HTTPS and HTTP redirection; troubleshooting a Node application crash and configuring systemd auto-restart; auditing exposed ports, listening status, and firewall rules and flagging content that should not be exposed externally.

Platform support and limitations

cygnus-ssh-mcp can connect from any client (Windows, Linux, macOS) to any target server; Windows targets require OpenSSH Server to be installed and running.

Access to the alternate platform (flex) is currently an in-progress feature and has been verified on several real devices, but routers/NAS/embedded systems vary greatly, and unsupported devices may be encountered. In addition to Linux, macOS, and Windows, SSH targets that can respond to basic shell commands will report os_type: "flex". On connection, a one-time capability probe is performed to check the specific shell/coreutils features that the tools depend on (such as GNU find -printf, stat -c, du -sb, tar --strip-components, ps -o pgid=, xargs -0, etc.); many embedded/BusyBox devices support only a smaller set of flags. The results are returned by ssh_conn_connect as capabilities and capability_warnings; when capabilities are missing, the tools give a clear error and point out the specific unavailable items, and when alternatives exist they also give specific fallbacks rather than silently degrading. If a portable alternative exists (such as glob search and directory size that do not depend on GNU find -printf), the tools use it directly. The probe also checks whether SFTP is available: some devices do not have SFTP (such as OpenWrt), and some SFTP shows a different filesystem from the shell (such as Synology DSM's shared-only SFTP); SFTP-based file tools explain the situation and point to ssh_cmd_run instead of giving a wrong answer. Known limitation: some devices completely deny SSH shell access for a certain account, that is,even if that account has administrator privileges, the manifestation is that after successful login all commands (including a bare echo) fail immediately; capability probing cannot solve this, and ssh_conn_connect will explain the situation in the failure rather than giving a generic error. For complete details, the capability list, and current gaps, see docs/26-alternate-platforms.md.

Host configuration supports alias connections, and existing hosts can be updated via ssh_host_update for a single field without losing the remaining fields, or ssh_host_use_config can be used to switch all host tools for the session to an alternate configuration file, making it convenient to maintain separate host lists by project or environment.

Regarding charges, pricing, specific installation commands, and code content, the materials do not provide complete information, so they are not provided for now.