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

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.

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 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)

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.

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.

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

{
  "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 instead of Claude Desktop? It reads its own project-level .mcp.json file (in your project root) rather than claude_desktop_config.json, and its schema supports a couple of extra fields Desktop doesn't have:

{
  "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 - the directory the server process runs from. Claude Desktop has no equivalent - it doesn't expose a configurable working directory at all, which is exactly why the Desktop examples above always use absolute paths.
• auto_start - whether Claude Code starts this server automatically. Claude Desktop always auto-starts every configured server; there's no toggle for it.

Everything else - the --config argument, and the PATH/backslash caveats from the warning above - applies the same way to both clients.

3. Start managing servers

Just say:

"Connect to PROD and tell me about the machine - hardware, status, everything"

"Connect to the GPU box and tell me how many graphics cards it has and how much total VRAM"

"Edit /etc/nginx/nginx.conf and change worker_connections to 2048"

"Find all .log files larger than 100MB in /var/log"

It handles multi-step jobs just as easily - install packages, edit configs, open firewall ports, and restart services, all in one request:

"Install PostgreSQL, set it to listen on all interfaces, add a pg_hba.conf rule for remote connections, open port 5432 in the firewall, and create a database called analytics"

"Set up a full LAMP stack, download the latest WordPress, configure wp-config.php with a new database, and get the site running at /var/www/wordpress"

"Get a Let's Encrypt certificate for example.com, configure nginx to serve it over HTTPS, and redirect all HTTP traffic to it"

"My Node app in /opt/api keeps crashing - check the logs, find out why, and set it up as a systemd service that restarts automatically"

"Audit PROD's security - check what ports are open, what's actually listening on them, whether the firewall rules match, and flag anything that looks like it shouldn't be exposed to the internet"

Platform Support

cygnus-ssh-mcp works from any client (Windows, Linux, macOS) to any target server:

Windows targets require OpenSSH Server installed and running.

Connecting to Alternate Platforms

Beyond Linux, macOS, and Windows, cygnus-ssh-mcp connects to any SSH target that responds to a basic shell command - routers, NAS boxes, BSD-kernel appliances, and other embedded Linux devices. These report os_type: "flex".

On connect, a one-time capability probe checks the specific shell/coreutils features this project's tools depend on (GNU find -printf, stat -c, du -sb, tar --strip-components, ps -o pgid=, xargs -0, and more) - many embedded/BusyBox-based devices only support a smaller flag set than full GNU coreutils. The results come back from ssh_conn_connect as capabilities and, for anything missing, capability_warnings. A tool that needs a missing capability fails with a clear error naming exactly what's unavailable and, where one exists, a concrete fallback - nothing silently degrades. Where a portable alternative exists (e.g. glob search and directory size without GNU find -printf), the tool simply uses it.

The probe also checks that SFTP is usable: some devices have no SFTP at all (OpenWrt), and some offer an SFTP that shows a different filesystem than the shell (Synology DSM's share-only SFTP). Either way, SFTP-based file tools then say so and point to ssh_cmd_run, instead of giving wrong answers.

Verified against (each by an automated suite that walks an everyday administration workflow and checks every tool's answer against the shell):

Known limitation: some devices reject SSH shell access entirely for an account, even one with admin-level permissions - this shows up as every command (even a bare echo) failing immediately after a successful login. No capability probe can fix that; ssh_conn_connect explains the situation in that failure rather than a generic error.

Full details, capability list, and current gaps: docs/26-alternate-platforms.md.

Features

Host Configuration

Stop typing credentials. Connect by alias.

["admin@server.com"]
password = "secret"
port = 22
alias = "web"

Then just: "Connect to WEB"

Supports password, SSH key, and encrypted keys with passphrase.

Update a field on an existing host without losing the rest (ssh_host_update), or switch every host tool to an alternate config file for the session (ssh_host_use_config) - handy for keeping separate host lists per project or environment.

Line-Level File Editing

Edit config files with surgical precision—no download/upload needed.

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

Safety built-in: Operations fail if the match isn't unique—no accidental mass edits.

Background Task Management

Launch long-running processes and check back later.

# 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)

Comprehensive Sudo Support

Every tool supports use_sudo. Password is handled automatically.

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)

Three-Way Timeout System

Never get stuck on a hanging command - and never lose track of a long one either.

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 and wait_timeout never kill the remote command - they hand off to background monitoring so you can check back later (ssh_cmd_check_status), read output collected so far (ssh_cmd_output), or decide to end it early (ssh_cmd_kill). Only runtime_timeout ever terminates anything.

A single call never blocks longer than 50 seconds (--max-wait / MCP_SSH_MAX_WAIT), because many MCP clients (e.g. OpenCode) abort a tool call at 60s and the handoff would be lost. Longer commands just return a normal wait_timeout handoff with wait_capped: true - poll them, or use ssh_task_launch for anything that runs for minutes.

Full Unicode Support

Write and read files with emojis, international text, and special characters—on all platforms.

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

How it works: ssh_file_read and ssh_file_write use SFTP for direct binary transfer, completely bypassing shell encoding issues. This means Unicode works perfectly even on Windows targets where PowerShell's console encoding would normally corrupt special characters. The server's own PowerShell scripts write UTF-8 too, so file names in Windows results (delete previews, glob search, listings) keep their exact spelling. Line edits keep a file's own line endings (CRLF stays CRLF).

Windows Server Support

Full support for Windows targets with OpenSSH Server:

• PowerShell & CMD command execution
• Windows path handling (backslashes, drive letters, UNC paths)
• Administrator detection — shows if session has elevated privileges
• SFTP-based file operations — Unicode-safe, no encoding issues

Note: use_sudo is ignored on Windows (no sudo equivalent). For elevated operations, connect with an Administrator account.

And Much More...

• Command history with output retention and pattern filtering
• Recursive directory operations: search, copy, delete with dry-run
• Archive operations: create and extract tar.gz
• System info: OS version, memory, disk, CPU, uptime
• Pattern search: regex and plain text in files
• Alternate host config files: switch host lists per project/environment without restarting

All 46 Tools

Connection & Host Management (12 tools)

Command Execution (6 tools)

Background Tasks (3 tools)

File Operations (12 tools)

Directory Operations (11 tools)

Archive Operations (2 tools)

Documentation

Full docs site: cygnussystems.github.io/cygnus-ssh-mcp — searchable, with navigation. Or browse the raw files directly in docs/:

• Overview
• Installation
• Platform Compatibility
• Windows Support
• Alternate Platforms (flex)
• Host Configuration
• Tools Reference
• Command Execution
• Process Management
• Logging
• Claude Desktop Setup

Use Cases

• DevOps Automation — Deploy, configure, and manage servers via AI
• Log Analysis — Search and analyze logs across multiple servers
• Configuration Management — Edit configs with precision line operations
• Backup & Recovery — Create archives, transfer files, restore backups
• System Monitoring — Check status, verify services, monitor processes
• Security Auditing — Search for sensitive patterns, verify configurations

License

GPL-3.0 — Free and open source.