ssh-mcp v5.0

Unified MCP server for persistent SSH work across Linux hosts, network devices, and offensive pentest environments.

Features (7 Unified Tools)

• ssh_session: Persistent SSH connections (connect/disconnect/list), jump hosts (bastions), zlib compression, proactive keepalive

• ssh_server: Credential-safe server inventory management (save/remove/list) via Windows Credential Manager

• ssh_exec: Unified shell execution (standard sync, sudo with automated prompt detection & secret masking, background job dispatching)

• ssh_job: Background job supervision (status, realtime log streaming tail, kill)

• ssh_sftp: File & recursive directory transfers (upload, download, upload_dir, download_dir, list) with configurable timeouts

• ssh_network: Network automation for Cisco, MikroTik, FortiGate, Juniper (interactive exec, config push, backup, safe dry-run restore, diff)

• ssh_tunnel: TCP port forwarding and dynamic SOCKS5 proxy server

Related MCP server: SSH MCP Server

Quick Start

1. Save a server (once)

ssh_server(
    action='save',
    alias='vps',
    host='192.168.10.1',
    username='admin',
    password='your-password',
    auto_connect=True  # Auto-connect on startup
)

2. Connect (simple mode)

ssh_session(action='connect', alias='vps')  # Loads credentials automatically

3. Execute commands

ssh_exec(alias='vps', command='df -h')
ssh_exec(alias='vps', command='systemctl restart nginx', sudo_password='...')
ssh_exec(alias='vps', command='nmap -sS -p- 10.0.0.0/24', background=True, label='full-scan')

4. SFTP & SOCKS5 Proxy

# Recursive download without manual zip:
ssh_sftp(action='download_dir', alias='vps', remote_path='/home/user/app', local_path='D:\\home\\app')

# Dynamic SOCKS5 proxy on port 1080:
ssh_tunnel(action='start_socks', alias='vps', label='socks-vps', local_port=1080)

What's New in v4.0

Smart Connection Mode

• ssh_connect now accepts just an alias to load credentials automatically

• No need to provide host, username, password every time

• Fixes Claude Code integration issues

Critical Fixes

• Timeout handling: Now raises TimeoutError instead of silently returning incomplete buffers

• Rate limiting: 100ms minimum between network commands to prevent device saturation

• Magic numbers eliminated: Named constants for shell dimensions

Documentation

• New CLAUDE_CODE_USAGE.md with complete usage examples

• New CLAUDE_CODE_SETUP.md for configuration

• New CHANGELOG.md with full version history

Security Model

servers.json only keeps non-sensitive metadata. Secrets live in Windows Credential Manager under targets like:

• ssh-mcp:<alias>:password

• ssh-mcp:<alias>:key_passphrase

Host Key Policy

• strict: default, rejects unknown host keys (production)

• auto_add: accepts unknown host keys (lab only)

Network Devices

Supported device types:

• cisco - Cisco IOS/IOS-XE

• cisco_xr - Cisco IOS-XR

• mikrotik - MikroTik RouterOS

• fortigate - FortiGate FortiOS

• juniper - Juniper JunOS

• generic - Linux/Unix (default)

Example: Cisco backup

# Save once
ssh_save_server(
    alias='cisco-core',
    host='10.0.0.1',
    username='admin',
    password='...',
    device_type='cisco',
    auto_connect=True
)

# Connect
ssh_connect(alias='cisco-core')

# Backup config
ssh_backup_config(alias='cisco-core', device_type='cisco')
# Saved to: backups/cisco-core/cisco-core_2026-05-31_14-30-00.txt

# Execute commands
ssh_exec_network(
    alias='cisco-core',
    commands=['show version', 'show ip interface brief'],
    device_type='cisco'
)

# Push config
ssh_push_config(
    alias='cisco-core',
    config='''
interface GigabitEthernet0/1
 description Uplink to Core
 ip address 10.0.1.1 255.255.255.0
 no shutdown
''',
    device_type='cisco',
    save_config=True
)

Usage with Claude Code

See CLAUDE_CODE_USAGE.md for detailed examples.

TL;DR:

1. Save: ssh_server(action='save', alias='vps', host='192.168.10.1', username='admin', password='...')
2. Connect: ssh_session(action='connect', alias='vps')
3. Execute: ssh_exec(alias='vps', command='df -h')

7 Unified Tools

1. ssh_session

• connect - Establish or reuse persistent SSH connection (smart mode: just provide alias)

• disconnect - Close connection, tunnels, SOCKS proxies, and jobs

• list - List all active connections with uptime, tunnels, proxies, and background jobs

2. ssh_server

• save - Save/update server in servers.json (secrets securely kept in Credential Manager)

• remove - Delete server from inventory

• list - List all saved servers

3. ssh_exec

• Standard sync execution (command)

• Sudo execution with prompt detection (sudo_password)

• Background execution (background=True, label='...')

4. ssh_job

• status - Check background job status or list all jobs

• tail - Stream last N lines of stdout/stderr

• kill - Terminate running background job

5. ssh_sftp

• upload / download - Transfer single files with configurable timeout

• upload_dir / download_dir - Recursive directory transfers without manual zip

• list - List remote files and directories

6. ssh_network

• exec - Run sequence of interactive commands on network devices

• push - Push multiline configuration block (with auto-backup)

• backup - Backup running config to timestamped local file

• restore - Restore config (dry-run by default, confirm=True to apply)

• diff - Compare two configs or current config vs backup

7. ssh_tunnel

• start / stop - Persistent local port forwarding (TCP tunnels)

• start_socks / stop_socks - Dynamic SOCKS5 proxy server

• list - List active tunnels and proxies

Installation in MCP Clients (Claude Desktop, OpenCode, Cursor, Windsurf)

Option 1: uvx (Instant - No Installation Required)

Add directly to your MCP client configuration (claude_desktop_config.json, opencode.json, etc.):

{
  "mcpServers": {
    "ssh-mcp": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/Steph-ux/ssh-mcp.git", "ssh-mcp"]
    }
  }
}

Option 2: pip install

pip install git+https://github.com/Steph-ux/ssh-mcp.git

Then in your MCP config:

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

Option 3: Local Clone (Development)

git clone https://github.com/Steph-ux/ssh-mcp.git
cd ssh-mcp
pip install -e .

Architecture

• SSHPool: Thread-safe connection pool with automatic reconnection and jump host chaining

• SSHConnection: Per-connection state with RLock for thread safety

• ThreadPoolExecutor: Async/await wrapper for Paramiko

• Rate limiter: 100ms minimum between commands to prevent device saturation

• SecretStore: Windows Credential Manager on Windows, keyring on Linux/macOS

Run Tests

pytest tests

Documentation

• CLAUDE_CODE_USAGE.md - Usage examples for AI agents

• CLAUDE_CODE_SETUP.md - Complete client configuration guide

• CHANGELOG.md - Version history and migration guide

License

MIT