Cygnus Ssh MCP

What cygnussystems/cygnus-ssh-mcp MCP server does

The cygnussystems/cygnus-ssh-mcp MCP server exposes 46 purpose-built tools for administering machines reachable through SSH. It supports Linux, macOS, and Windows targets, along with a flex platform type for devices such as routers, NAS systems, and other hosts with non-standard or reduced shells.

Instead of relying on one generic shell tool, the server separates common administration tasks into operations for commands, files, processes, directories, archives, and host management. An MCP-compatible client can use those operations to inspect a host, update a remote configuration file, transfer and extract an artifact, or start work that continues after the initial request.

How it works

The cygnussystems/cygnus-ssh-mcp MCP server runs locally and opens standard SSH connections to hosts defined in a TOML file. Each entry identifies a user and host, plus a port and either a password or private-key file. Optional aliases let clients refer to a machine by a shorter name. A configured sudo password enables privileged operations on Linux and macOS; the regular login password can be reused when applicable.

File content is handled through SFTP where appropriate. This avoids relying on a target shell's console encoding and is intended to preserve non-ASCII text on Windows systems. Background-task tools track the remote process, provide output later, and support termination. The implementation also accounts for platform-specific process identifiers and exit-code behavior.

The target machine must already run an SSH service. The MCP server supplies the management interface, not the SSH daemon itself.

Setup and configuration

Install the package with pip or launch it without a persistent installation through uvx cygnus-ssh-mcp. On its first start, it creates ~/.mcp_ssh_hosts.toml with restrictive permissions when no host file exists. If that path is absent, it can use ./mcp_ssh_hosts.toml instead. Hosts may also be added through the ssh_conn_add_host tool.

A host entry requires a port and either password or keyfile. Supported optional settings include alias, description, sudo_password, and key_passphrase. Key paths can use the home-directory shorthand shown in the project documentation. When key authentication is used without a login password, privileged commands require a separate sudo password or passwordless sudo on the target.

Linux and macOS hosts need SSH enabled. Windows targets require OpenSSH Server, with the README documenting Windows Server 2019+, Windows 10, and Windows 11 as supported environments. Windows Server 2016 and other edge cases have separate guidance.

Tools and capabilities

The cygnussystems/cygnus-ssh-mcp MCP server includes tools for:

• Running remote commands and retaining command history with output.
• Executing commands with sudo where the host configuration permits it.
• Editing individual file lines without a download, local edit, and re-upload cycle.
• Creating, monitoring, and stopping background tasks.
• Listing, creating, moving, copying, and removing directories recursively.
• Creating and extracting archives.
• Reading and writing files through SFTP for Unicode-safe handling.
• Connecting to configured hosts by alias.
• Inspecting processes on Windows SSH targets.

These capabilities fit tasks such as checking system resources and logs, patching configuration files, deploying an archive, restarting a service, or retrieving output from a long-running command.

Limitations and notes

SSH must be installed and running on every target, and the configured account must have the permissions required for requested operations. Sudo support is described for Linux and macOS; Windows administration follows the permissions available to the SSH account.

flex support is still under development. It has been tested with several alternate devices, but behavior may vary across routers, NAS products, embedded systems, and other shells that differ from standard Linux, macOS, or Windows environments.

The project is distributed under GPL version 3. The README identifies Claude Desktop, Claude Code, OpenCode, and other MCP-compatible clients as usable clients; this listing specifically records Claude Desktop among the supported client slugs.