Cygnus Ssh MCP

cygnus-ssh-mcp

Cross-platform SSH MCP server with 46 purpose-built tools for real server management by AI agents

*Give Claude, OpenCode, or any MCP-compatible AI assistant full control of your Linux, macOS, and Windows servers with 46 specialized tools*

Prerequisites · Installation · Quick Start · Features · Documentation

---

[!TIP]

A note from the author: I've been running this daily since April 2025 — over a

year now — to manage a dozen+ machines and devices, plus a Proxmox host running

30+ containers, across a network tied together with Tailscale. It started as a

tool to solve my own problem, and it's saved me a huge amount of manual work ever

since. After a year of running it against Linux, I've since added support for

Windows, macOS, and other devices with reduced shells like BusyBox. I'm

open-sourcing it now because I think anyone running real infrastructure will find

it just as useful. This is a young *public* repo, but the tool behind it isn't new

or unproven — it's been battle-tested against my own servers for over a year.

If you find it useful, a ⭐ star or a mention to someone who manages their own

infrastructure goes a long way for a project this new — thank you!

---

Why cygnus-ssh-mcp?

cygnus-ssh-mcp is an MCP server - usable from Claude Desktop, Claude Code, OpenCode, or any other MCP-compatible client - that connects your AI assistant directly to your remote servers over SSH, exposing 46 purpose-built tools instead of one generic command-runner. It turns natural-language requests into real systems administration - connecting by alias, editing files, managing background processes, handling sudo - across Linux, macOS, and Windows targets alike.

Doing that properly means solving a pile of genuinely hard, per-platform problems that a naive ssh wrapper never has to face - and that this project hit and fixed the hard way, including:

• Getting a *real* PID back from a Windows target, instead of a meaningless local channel number
• Recovering the actual exit code when Win32-OpenSSH silently flattens it to 1
• Reading file contents via SFTP instead of Get-Content, because PowerShell's console encodes stdout in its OEM code page and corrupts anything non-ASCII
• Killing a sudo'd background process without leaving its privileged child orphaned or blindly firing SIGKILL at the wrong PID

None of this shows up until you actually run these tools against real Linux, macOS, and Windows targets under real conditions - which is exactly how every one of these was found and fixed here, not guessed at from documentation.

Beyond Linux, macOS, and Windows, cygnus-ssh-mcp can also reach further - routers, NAS boxes, and other non-standard SSH targets connect too, via a flex platform type and a capability probe that detects what each device's shell can actually do. See Connecting to Alternate Platforms below.

[!WARNING]

Alternate-platform (`flex`) support is a work in progress. It's been

verified against several real devices, but the space of routers/NAS/embedded

systems is huge - expect rough edges on hardware that hasn't been tried yet.

Example agent tasks

Ask your MCP-capable agent to:

• "Check disk space, memory, uptime, and recent logs on my web host."
• "Patch this remote config file safely and show me the diff."
• "Upload this build artifact, extract it, and restart the service."
• "Start this command in the background and fetch the output later."
• "Inspect running processes on my Windows SSH host."

---

Prerequisites: SSH on Your Target Servers

cygnus-ssh-mcp connects over standard SSH - it doesn't provide SSH itself, so each server you want to manage needs an SSH server already installed and running.

Linux - usually pre-installed on server distros; if not:

sudo apt install openssh-server   # Debian/Ubuntu

sudo systemctl enable --now ssh

macOS - enable Remote Login in System Preferences → Sharing, or from the terminal:

sudo systemsetup -setremotelogin on

Windows (Server 2019+, or Windows 10/11) - OpenSSH Server is an optional feature:

Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0

Start-Service sshd Set-Service -Name sshd -StartupType 'Automatic'

See [Windows Support](docs/25-windows-support.md) for Windows Server 2016 and other edge cases.

---

Installation

Pick one of the two options below - they're independent tools that don't share storage, so commands from one won't see or affect what the other did.

Option A: pip (a persistent install)

pip install cygnus-ssh-mcp

Uninstalling or upgrading:

pip uninstall cygnus-ssh-mcp

pip install --upgrade cygnus-ssh-mcp

Option B: uvx (no install at all)

[!NOTE]

What's `uvx`? It's part of uv (a fast Python

package manager) - uvx downloads a package into a disposable,

isolated cache and runs it immediately, without installing it into your system

Python, a project, or anywhere pip can see. Nothing lingers afterward for you

to manage. It's the easiest option if you just want your MCP client to launch

this server without thinking about Python environments at all.

uvx cygnus-ssh-mcp

There's nothing to "uninstall" - uvx re-resolves and re-fetches the latest version on every run anyway. To force a fresh fetch or clear its cache instead:

uvx --refresh cygnus-ssh-mcp   # force this run to ignore the cache

uv cache clean # clear uv's entire package cache

If you want a uvx-style setup that *does* persist (so it doesn't re-fetch every time) and can be upgraded deliberately, use uv tool install cygnus-ssh-mcp instead - manage that with uv tool uninstall cygnus-ssh-mcp / uv tool upgrade cygnus-ssh-mcp. This is still separate from pip (Option A) - don't mix pip commands with anything set up via uv/uvx, they can't see each other.

---

Quick Start

1. Add your hosts

You don't need to create anything by hand - the first time the server starts, it automatically creates an empty host config file at ~/.mcp_ssh_hosts.toml (secure 0o600 permissions) if nothing is there yet. Just open that file (or use ssh_conn_add_host from within your AI assistant) and add entries like:

# Minimal (password auth) - only required fields

["user@server.example.com"] password = "your_password" port = 22

With alias and sudo (most common setup)

["admin@production.example.com"] 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

["deploy@staging.example.com"] keyfile = "~/.ssh/id_ed25519" port = 22 alias = "staging"

Windows Server (requires OpenSSH)

["administrator@winserver.example.com"] password = "your_password" port = 22 alias = "win-prod"

Required fields: port + (password OR keyfile) Optional fields: alias, description, sudo_password, key_passphrase

sudo_password is optional if your account uses password auth - when omitted, the regular password is reused for use_sudo operations too. It's only required if your sudo password differs from your login password, or if you're using SSH key auth (keyfile) with no password field at all - in that case, either set sudo_password explicitly or configure passwordless sudo on the server.

[!TIP]

Host file locations: Default is ~/.mcp_ssh_hosts.toml. Falls back to ./mcp_ssh_hosts.toml if not found.

Use --config /path/to/hosts.toml for a custom location. If a file already exists

at whichever path is used, it is never overwritten or reset - auto-creation

only ever happens when nothing is there yet.

[!WARNING]

Watch for hidden file extensions. If you create this file yourself in Notepad

or TextEdit, Windows and macOS both hide known extensions by default - a file you

named mcp_ssh_hosts.toml can silently actually be saved as

mcp_ssh_hosts.toml.txt, and the server will never find it. Turn on "show file

extensions" in Explorer/Finder, or verify from a terminal:

ls -la ~/.mcp_ssh_hosts.toml* (macOS/Linux) or

dir %USERPROFILE%\.mcp_ssh_hosts.toml* (Windows) - either should show exactly

one file, with no extra extension after .toml.

2. Add to your MCP client

Most MCP clients (Claude Desktop, Claude Code, OpenCode, Cursor, Cline, Windsurf, and others) use the same mcpServers JSON shape shown below - only the config file's name and location differ per client. Claude Desktop is used as the concrete example here; see the Claude Code note further down for one client that differs, or check your own client's docs for its config file's path.

[!WARNING]

**Python must be on PATH for "command": "cygnus-ssh-mcp" (below) to work at

all.** This is the most common reason an MCP client fails to start the server

(or the tool list never appears) - and with Python often installed in several

different places on one machine, it's easy to hit. Check first with:

`bash

python --version # Windows/macOS/Linux

python3 --version # macOS/Linux, if the above isn't found

`

If that fails with "not recognized"/"command not found", Python isn't on PATH -

fix that first (reinstall Python with "Add to PATH" checked on Windows, or add it

to your shell profile), or work around it entirely by finding the full path to

the installed executable instead: where cygnus-ssh-mcp (Windows) or

which cygnus-ssh-mcp (macOS/Linux), then use that directly as command:

`json

{

"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"]

}

}

}

`

For Claude Desktop, edit claude_desktop_config.json:

{

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

Or with a custom hosts file location:

{

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

On Windows, use an absolute path with escaped backslashes (JSON needs \\, not a single \):

{

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

Using [Claude Code](https://claude.com/claude-code) instead of Claude Desktop? It reads its ow