Installation¶

Requirements¶

Python 3.10 or higher
pip or uv package manager

Install from PyPI¶

pip install cygnus-ssh-mcp

Or with uv:

uv pip install cygnus-ssh-mcp

Run without Installing¶

Use uvx to run directly without permanent installation:

uvx cygnus-ssh-mcp --config ~/.mcp_ssh_hosts.toml

This downloads and runs the latest version each time.

Verify Installation¶

cygnus-ssh-mcp --help

Expected output:

usage: cygnus-ssh-mcp [-h] [--config CONFIG] [--max-wait MAX_WAIT]
                      [--max-output MAX_OUTPUT]
                      [--inline-output INLINE_OUTPUT]
                      [--output-memory OUTPUT_MEMORY]

SSH MCP Server

options:
  -h, --help            show this help message and exit
  --config CONFIG       Path to SSH hosts configuration file (TOML format)
  --max-wait MAX_WAIT   Max seconds a single ssh_cmd_run call blocks before
                        handing off with status='wait_timeout' (default:
                        $MCP_SSH_MAX_WAIT or 50; 0 disables the cap)
  --max-output MAX_OUTPUT
                        Output kept in memory per command and stream, in
                        bytes; the earliest lines beyond it are dropped
                        (default: $MCP_SSH_MAX_OUTPUT or 2097152 = 2 MB)
  --inline-output INLINE_OUTPUT
                        Most recent output returned inline per stream by
                        ssh_cmd_run, in bytes; the rest can be paged with
                        ssh_cmd_output (default: $MCP_SSH_INLINE_OUTPUT or
                        32768)
  --output-memory OUTPUT_MEMORY
                        Total output memory across the command history, in
                        bytes (default: $MCP_SSH_OUTPUT_MEMORY or 52428800 =
                        50 MB)

Uninstalling / Upgrading¶

pip uninstall cygnus-ssh-mcp
pip install --upgrade cygnus-ssh-mcp

If you installed with uv tool install cygnus-ssh-mcp instead of pip, use uv tool uninstall cygnus-ssh-mcp / uv tool upgrade cygnus-ssh-mcp. uvx doesn't persist an install at all - it re-fetches the latest version on every run, so there's nothing to uninstall and no separate upgrade step.

Uninstalling only removes the Python package - your host config file (~/.mcp_ssh_hosts.toml) and any Claude Desktop config changes are left in place, since they may contain saved credentials or configuration you want to keep. Remove them yourself if you no longer need them.

Claude Desktop Configuration¶

After installation, add to your claude_desktop_config.json:

Using pip install:

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

Using uvx (no permanent install):

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

See Claude Desktop Setup for detailed configuration options.

Note: none of the --config paths above need to already exist - the server creates an empty host configuration file at that path (with secure 0o600 permissions) the first time it starts if nothing is there yet. See Host Configuration for the exact lookup order and auto-creation behavior.