mcp-ssh

MCP server for running commands over persistent SSH sessions. Connects AI assistants (Claude, Cursor, etc.) to remote hosts — Linux servers, routers, switches, and any SSH-accessible device.

Built with the help of Claude AI (Anthropic).

Features

• Persistent SSH sessions — connections are pooled and reused; no reconnect overhead per command

• Two execution modes — stateless exec for POSIX hosts, stateful PTY shell for interactive CLIs (Cisco, MikroTik, etc.)

• Safety layer — configurable regex deny-list blocks destructive commands (rm -rf /, mkfs, reboot, etc.)

• Append-only audit log — every command, decision, and exit code recorded to JSONL

• Two transports — stdio for local use, SSE with Bearer token auth for remote/Docker deployment

• No secrets in config — passwords and passphrases are referenced by environment variable name, not stored

Related MCP server: MCP ShellKeeper

MCP Tools

All tools accept confirm_dangerous=true to override a safety block when the command is intentional.

Quick Start

Install

git clone https://github.com/your-username/mcp-ssh
cd mcp-ssh
poetry config virtualenvs.in-project true --local
poetry install

Configure hosts

Use the interactive manager to add, edit, or remove hosts without touching YAML by hand:

python manage_hosts.py
# or with an explicit config path:
MCP_SSH_CONFIG=/path/to/hosts.yaml python manage_hosts.py

The script provides a menu-driven terminal UI: list hosts, add, edit (current values shown as defaults), and delete with confirmation. Validates IP/hostname, port range, regex syntax, and warns if a referenced env var is not exported.

Alternatively, copy hosts.example.yaml and edit manually:

hosts:
  home-server:
    host: 192.168.1.10
    user: admin
    auth:
      method: key
      key_path: ~/.ssh/id_ed25519
    shell: posix

  cisco-switch:
    host: 192.168.1.1
    user: cisco
    auth:
      method: password
      password_env: CISCO_PASS      # name of env var, not the password itself
    shell: cli
    prompt_regex: '[\w.-]+[>#]\s*$'

settings:
  idle_timeout: 600
  command_timeout: 60
  audit_log: ~/.mcp_ssh/audit.log

Export secrets before starting:

export MCP_SSH_CONFIG=/path/to/hosts.yaml
export CISCO_PASS='my-password'

Run (stdio — local use)

poetry run mcp-ssh

Register poetry run mcp-ssh (with env vars set) as a stdio MCP server in your AI assistant.

Run (SSE — remote / Docker)

export MCP_TRANSPORT=sse
export MCP_AUTH_TOKEN=$(python -c "import secrets; print(secrets.token_hex(32))")
export MCP_PORT=8000
poetry run mcp-ssh

MCP_HOST defaults to 127.0.0.1. Set MCP_HOST=0.0.0.0 only when a reverse proxy handles TLS and auth in front.

Shell Types

cli hosts require prompt_regex — a regex matching the device prompt (e.g. [\w.-]+[>#]\s*$).

Safety

Default deny patterns block:

rm -rf /      mkfs      reboot      shutdown
dd of=/dev/*  write erase   erase startup-config

Extend or override in hosts.yaml:

settings:
  deny_patterns:
    - "rm\\s+-rf\\s+/"
    - "your-custom-pattern"

Pass confirm_dangerous=true to any tool to override a block when you know it is intentional.

Docker / Portainer

See docs/portainer-deployment.md for a full guide including nginx reverse proxy setup.

docker compose up -d

Key environment variables for the container:

Tests

# Unit tests (no Docker required)
poetry run pytest -m "not integration"

# Full suite (requires docker-compose SSH server)
docker compose up -d
poetry run pytest
docker compose down

Architecture

AI Agent (Claude / Cursor)
    │  stdio or HTTP SSE + Bearer token
    ▼
mcp-ssh server
    ├── safety.classify_command()   ← regex deny-list
    ├── audit.log()                 ← append-only JSONL
    └── SessionManager.get()        ← pooled SSH connections
            ├── SSHConnection.run_exec()      ← POSIX stateless
            └── SSHConnection.run_in_shell()  ← PTY stateful (ShellSession)

Key modules: mcp_ssh/server.py · mcp_ssh/session_manager.py · mcp_ssh/connection.py · mcp_ssh/safety.py · mcp_ssh/audit.py

License

MIT