cygnus-ssh-mcp

The most powerful SSH MCP server for AI assistants

Give Claude full control of your Linux, macOS, and Windows servers with 43 specialized tools

Installation · Quick Start · Features · Documentation

Why cygnus-ssh-mcp?

Most SSH MCP servers let you run commands. cygnus-ssh-mcp lets you manage servers.

Installation

pip install cygnus-ssh-mcp

Or run without installing using uvx:

uvx cygnus-ssh-mcp

Quick Start

1. Create your hosts file

Create ~/.mcp_ssh_hosts.toml:

# 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

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.

2. Add to Claude Desktop

Edit your 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"]
    }
  }
}

3. Start managing servers

In Claude, just say:

"Connect to prod and show me the disk usage"

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

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

Platform Support

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

Windows targets require OpenSSH Server installed and running.

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.

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(path="/etc/app/config.yaml", content="...", use_sudo=True)
ssh_dir_mkdir(path="/opt/myapp", use_sudo=True)
ssh_archive_extract(archive="/backup.tar.gz", dest="/", use_sudo=True)

Dual Timeout System

Never get stuck on a hanging command.

ssh_cmd_run(
    command="./long_script.sh",
    io_timeout=60.0,       # Kill if no output for 60s
    runtime_timeout=3600.0  # Kill if total time exceeds 1 hour
)

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.

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

All 43 Tools

Connection & Host Management (10 tools)

Command Execution (6 tools)

Background Tasks (3 tools)

File Operations (12 tools)

Directory Operations (10 tools)

Archive Operations (2 tools)

Documentation

Detailed guides available in docs/:

• Overview

• Installation

• Platform Compatibility

• Windows Support

• 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.

Built by Cygnus Systems

Star this repo if you find it useful!