mcp-multi-ssh

MCP server for managing and executing commands on multiple remote servers via SSH.

Built for use with Claude Desktop and other MCP-compatible clients.

Features

• Multi-host SSH - configure and manage multiple server connections
• Connection pooling - automatic reconnect, keepalive, concurrent sessions
• CRUD for connections - create, read, update, delete connections at runtime
• Auth validation - requires password or private key, prevents invalid configs
• Command history - tracks executed commands with timestamps and exit codes
• Password masking - sensitive data never exposed in tool responses
• Minimal footprint - ~500 lines, SSH-only, no bloat

Installation

Claude Desktop / Claude.ai

Add to claude_desktop_config.json:

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "mcp-multi-ssh": {
      "command": "npx",
      "args": ["-y", "mcp-multi-ssh"]
    }
  }
}

Claude Code

claude mcp add mcp-multi-ssh -- npx -y mcp-multi-ssh

Or add to .mcp.json in your project root:

{
  "mcpServers": {
    "mcp-multi-ssh": {
      "command": "npx",
      "args": ["-y", "mcp-multi-ssh"]
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

{
  "mcpServers": {
    "mcp-multi-ssh": {
      "command": "npx",
      "args": ["-y", "mcp-multi-ssh"]
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json. Same JSON format as above.

VS Code + GitHub Copilot

Add to .vscode/mcp.json in your workspace:

{
  "servers": {
    "mcp-multi-ssh": {
      "command": "npx",
      "args": ["-y", "mcp-multi-ssh"]
    }
  }
}

Cline

Open Cline -> MCP Servers icon -> Edit MCP Settings, then add the same JSON as Claude Desktop.

OpenAI Codex CLI

codex mcp add mcp-multi-ssh -- npx -y mcp-multi-ssh

Zed

Add to Zed settings.json (via Agent Panel -> Settings):

{
  "context_servers": {
    "mcp-multi-ssh": {
      "command": {
        "path": "npx",
        "args": ["-y", "mcp-multi-ssh"]
      }
    }
  }
}

Compatibility Matrix

Tool	Config Location
Claude Desktop / Claude.ai	claude_desktop_config.json
Claude Code	.mcp.json
Cursor	.cursor/mcp.json
Windsurf	~/.codeium/windsurf/mcp_config.json
VS Code + Copilot	.vscode/mcp.json
Cline	MCP Settings JSON
Continue.dev	.continue/mcpServers/*.json
Zed	settings.json
Codex CLI	.codex/config.toml
Roo Code	MCP Settings JSON
Google Antigravity	~/.gemini/settings.json

Local install

npm install -g mcp-multi-ssh

Then in claude_desktop_config.json:

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

Configuration

Config file is loaded from (in order):

1. Path specified via --config flag
2. ./config.json in current directory
3. ~/.mcp-multi-ssh/config.json

Example config

{
  "ssh": {
    "enabled": true,
    "defaultTimeout": 60,
    "maxConcurrentSessions": 10,
    "keepaliveInterval": 5000,
    "keepaliveCountMax": 3,
    "readyTimeout": 30000,
    "connections": {
      "my-server": {
        "host": "example.com",
        "port": 22,
        "username": "deploy",
        "privateKeyPath": "/home/user/.ssh/id_rsa",
        "passphrase": "key-passphrase-if-encrypted"
      },
      "db-server": {
        "host": "10.0.0.5",
        "port": 22,
        "username": "admin",
        "password": "secret"
      }
    }
  },
  "logging": {
    "enabled": true,
    "maxHistorySize": 1000
  }
}

To generate a default config:

npx mcp-multi-ssh --init-config ~/.mcp-multi-ssh/config.json

Remote HTTP Server (Docker / Dokploy)

In addition to stdio, the server can run as a remote MCP over Streamable HTTP - reachable as a custom connector from Claude web/mobile. Start it with npm run start:http (or node dist/http.js), or build the included Dockerfile.

In HTTP mode the connection config comes from environment variables (not a config file), and the write tools (create/update/delete_ssh_connection) are disabled - the server is read/execute only.

Environment variables

Var	Required	Description
MCP_AUTH_TOKEN	yes	Bearer token clients must send in the Authorization header
PORT	no	Listen port (default 3000)
MCP_PATH	no	Endpoint path (default /mcp)
MCP_ENABLED	no	Set to false to refuse startup (kill switch)
SSH_TIMEOUT	no	Command timeout in seconds (default 60)
SSH_CONNECTIONS	one of	All connections as a single JSON object (format A)
SSH_<ID>_*	one of	Per-server vars (format B, see below)

If SSH_CONNECTIONS is set it takes precedence; otherwise the SSH_<ID>_* vars are collected.

Format A - one JSON var:

SSH_CONNECTIONS={"web1":{"host":"1.2.3.4","port":22,"username":"root","password":"secret"}}

Format B - per-server vars, no JSON escaping. The middle segment becomes the (lowercased) connection ID, so SSH_WEB1_HOST -> connection web1:

SSH_WEB1_HOST=1.2.3.4
SSH_WEB1_PORT=22          # optional, defaults to 22
SSH_WEB1_USER=root
SSH_WEB1_PASSWORD=secret  # or SSH_WEB1_KEY_B64

For key auth, base64-encode the OpenSSH key file (avoids newline escaping) and pass it as SSH_<ID>_KEY_B64, with optional SSH_<ID>_PASSPHRASE. The helper script does the encoding on any platform with Node:

node tools/key2env.mjs /path/to/id_ed25519 web1

Auth

Clients authenticate with a bearer token. The endpoint returns 401 without a valid Authorization: Bearer <MCP_AUTH_TOKEN> header. A GET /health endpoint (no auth) reports status and connection count. Since the endpoint is public, pair the token with a network allowlist (e.g. restrict to your MCP client's egress ranges) and a least-privilege SSH user where possible.

Tools

Tool	Description
ssh_execute	Execute a command on a remote host
ssh_disconnect	Close an SSH connection
create_ssh_connection	Add a new connection to config
read_ssh_connections	List all configured connections
update_ssh_connection	Modify an existing connection
delete_ssh_connection	Remove a connection from config
get_command_history	View recent SSH command history

Connection Config

Each connection requires:

Field	Required	Description
host	yes	Hostname or IP address
port	yes	SSH port
username	yes	SSH username
password	one of	Password authentication
privateKeyPath	one of	Path to private key file (OpenSSH/PEM format)
privateKey	one of	Private key content directly (OpenSSH/PEM); used by HTTP mode
passphrase	no	Passphrase for an encrypted private key
keepaliveInterval	no	Override global keepalive (ms)
keepaliveCountMax	no	Override max failed keepalives
readyTimeout	no	Override connection timeout (ms)

At least password or privateKeyPath must be provided.

Private keys must be in OpenSSH/PEM format. PuTTY .ppk files are not supported - convert them first via PuTTYgen (Conversions -> Export OpenSSH key).

Background

This project started as a fork of win-cli-mcp-server (now archived/deprecated). It has been rebuilt as a focused SSH-only MCP server - all Windows CLI functionality was removed, bugs were fixed, and the codebase was reduced by over 50%.

License

MIT