ssh-mcp-server

ssh-mcp-server

 

MCP server for executing commands, uploading and downloading files on remote servers via SSH. Zero-config for single servers — just pass credentials inline.

English

ssh-mcp-server is an MCP server for controlled SSH automation from AI tools. It supports command execution, file uploads/downloads, multi-server configs, async jobs, and clean AI-readable output.

Русский

ssh-mcp-server — MCP-сервер для контролируемой SSH-автоматизации из AI-инструментов. Он поддерживает выполнение команд, загрузку/скачивание файлов, конфигурации нескольких серверов, фоновые задачи и чистый вывод, удобный для AI.

Українська

ssh-mcp-server — MCP-сервер для контрольованої SSH-автоматизації з AI-інструментів. Він підтримує виконання команд, завантаження/скачування файлів, конфігурації кількох серверів, фонові задачі та чистий вивід, зручний для AI.

Features

• Command execution — sync/async modes, timeout, background polling
• Reliable file transfers — 5 automatic fallback strategies
• Multi-server — easy switching with workspace-based auto-selection
• AI-Native output — ANSI stripped, binary detected, control chars removed
• Zero-config mode — pass server credentials directly in MCP config, no extra files needed
• Fast — SFTP session caching, connection pooling, 64-stream parallel transfers

Tools

| Tool | Description | |------|-------------| | ssh_servers | List configured servers and their workspace bindings | | ssh_execute | Run a shell command (sync or async with polling) | | ssh_upload | Upload a local file to remote server | | ssh_download | Download a remote file to local machine |

Quick Start

Zero-Config (Inline)

No files needed — pass server credentials directly in your AI tool's MCP config: ``json { "ssh": { "command": "npx", "args": [ "-y", "@thesashadev/ssh-mcp-server", "--host", "1.2.3.4", "--username", "ubuntu", "--password", "your-password" ] } } ``

With Config File

For multi-server setups, create ssh-servers.json in your working directory: ``json { "servers": [ { "id": "dev", "name": "Dev Server", "host": "1.2.3.4", "username": "ubuntu", "password": "your-password", "workspaces": ["D:\\projects\\my-app"] } ] } ` Then run: `bash npx -y @thesashadev/ssh-mcp-server ``

🔌 Client Integration

<details> <summary><b>Claude Code (CLI)</b></summary>

Single server: ``bash claude mcp add ssh -- npx -y @thesashadev/ssh-mcp-server --host 1.2.3.4 --username ubuntu --password secret ``

Two servers: ``bash claude mcp add ssh -- npx -y @thesashadev/ssh-mcp-server \ --host 1.2.3.4 --username ubuntu --password secret --id dev \ --host 5.6.7.8 --username deploy --key ~/.ssh/id_rsa --id prod ``

Or with config file: ``bash claude mcp add ssh -- npx -y @thesashadev/ssh-mcp-server ` (Place ssh-servers.json` in your project root) </details>

<details> <summary><b>Claude Desktop</b></summary>

Edit claude_desktop_config.json:

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

Single server: ``json { "mcpServers": { "ssh": { "command": "npx", "args": [ "-y", "@thesashadev/ssh-mcp-server", "--host", "1.2.3.4", "--username", "ubuntu", "--password", "secret" ] } } } ``

Two servers: ``json { "mcpServers": { "ssh": { "command": "npx", "args": [ "-y", "@thesashadev/ssh-mcp-server", "--host", "1.2.3.4", "--username", "ubuntu", "--password", "secret", "--id", "dev", "--host", "5.6.7.8", "--username", "deploy", "--key", "~/.ssh/id_rsa", "--id", "prod" ] } } } `` </details>

<details> <summary><b>Cursor</b></summary>

Open Settings → Cursor Settings → MCP → + Add New MCP Server.

Or add to ~/.cursor/mcp.json:

Single server: ``json { "mcpServers": { "ssh": { "command": "npx", "args": [ "-y", "@thesashadev/ssh-mcp-server", "--host", "1.2.3.4", "--username", "ubuntu", "--password", "secret" ] } } } ``

Two servers: ``json { "mcpServers": { "ssh": { "command": "npx", "args": [ "-y", "@thesashadev/ssh-mcp-server", "--host", "1.2.3.4", "--username", "ubuntu", "--password", "secret", "--id", "dev", "--host", "5.6.7.8", "--username", "deploy", "--key", "~/.ssh/id_rsa", "--id", "prod" ] } } } `` </details>

<details> <summary><b>Windsurf</b></summary>

Edit ~/.codeium/windsurf/mcp_config.json (macOS/Linux) or %USERPROFILE%\.codeium\windsurf\mcp_config.json (Windows):

Single server: ``json { "mcpServers": { "ssh": { "command": "npx", "args": [ "-y", "@thesashadev/ssh-mcp-server", "--host", "1.2.3.4", "--username", "ubuntu", "--password", "secret" ] } } } ``

Two servers: ``json { "mcpServers": { "ssh": { "command": "npx", "args": [ "-y", "@thesashadev/ssh-mcp-server", "--host", "1.2.3.4", "--username", "ubuntu", "--password", "secret", "--id", "dev", "--host", "5.6.7.8", "--username", "deploy", "--key", "~/.ssh/id_rsa", "--id", "prod" ] } } } `` </details>

<details> <summary><b>Antigravity</b></summary>

Add to mcp_config.json:

Single server: ``json { "mcpServers": { "ssh": { "command": "npx", "args": [ "-y", "@thesashadev/ssh-mcp-server", "--host", "1.2.3.4", "--username", "ubuntu", "--password", "secret" ] } } } ``

Two servers: ``json { "mcpServers": { "ssh": { "command": "npx", "args": [ "-y", "@thesashadev/ssh-mcp-server", "--host", "1.2.3.4", "--username", "ubuntu", "--password", "secret", "--id", "dev", "--host", "5.6.7.8", "--username", "deploy", "--key", "~/.ssh/id_rsa", "--id", "prod" ] } } } `` </details>

<details> <summary><b>Codex</b></summary>

Add to codex.toml:

Single server: ``toml [mcp_servers."ssh"] command = "npx" args = [ "-y", "@thesashadev/ssh-mcp-server", "--host", "1.2.3.4", "--username", "ubuntu", "--password", "secret" ] enabled = true ``

Two servers: ``toml [mcp_servers."ssh"] command = "npx" args = [ "-y", "@thesashadev/ssh-mcp-server", "--host", "1.2.3.4", "--username", "ubuntu", "--password", "secret", "--id", "dev", "--host", "5.6.7.8", "--username", "deploy", "--key", "~/.ssh/id_rsa", "--id", "prod" ] enabled = true `` </details>

<details> <summary><b>Cody (Sourcegraph)</b></summary>

Edit ~/.config/cody/mcp_servers.json:

Single server: ``json { "mcpServers": { "ssh": { "command": "npx", "args": [ "-y", "@thesashadev/ssh-mcp-server", "--host", "1.2.3.4", "--username", "ubuntu", "--password", "secret" ] } } } ``

Two servers: ``json { "mcpServers": { "ssh": { "command": "npx", "args": [ "-y", "@thesashadev/ssh-mcp-server", "--host", "1.2.3.4", "--username", "ubuntu", "--password", "secret", "--id", "dev", "--host", "5.6.7.8", "--username", "deploy", "--key", "~/.ssh/id_rsa", "--id", "prod" ] } } } `` </details>

<details> <summary><b>Continue.dev</b></summary>

Add to .continue/config.json:

Single server: ``json { "mcpServers": [ { "name": "ssh", "command": "npx", "args": [ "-y", "@thesashadev/ssh-mcp-server", "--host", "1.2.3.4", "--username", "ubuntu", "--password", "secret" ] } ] } ``

Two servers: ``json { "mcpServers": [ { "name": "ssh", "command": "npx", "args": [ "-y", "@thesashadev/ssh-mcp-server", "--host", "1.2.3.4", "--username", "ubuntu", "--password", "secret", "--id", "dev", "--host", "5.6.7.8", "--username", "deploy", "--key", "~/.ssh/id_rsa", "--id", "prod" ] } ] } `` </details>

Configuration

Three ways to configure servers (in priority order):

1. CLI Arguments (Zero-Config)

Pass directly in your MCP config args: `` --host 1.2.3.4 --username ubuntu --password secret --host 1.2.3.4 --username deploy --key ~/.ssh/id_rsa ``

| Arg | Description | |-----|-------------| | --host | SSH host (starts a new server block) | | --port | SSH port (default: 22) | | --username | SSH user | | --password | Password auth | | --key | Path to private key | | --passphrase | Key passphrase | | --id | Server ID (default: "default") | | --name | Display name | | --remote-dir | Default remote directory | | --workspace | Local directory binding |

Multiple servers: repeat --host blocks: `` --host 1.2.3.4 --username dev --password pass1 --id dev --host 5.6.7.8 --username prod --key ~/.ssh/id_rsa --id prod ``

2. Environment Variables

For single-server setups via env: `` SSH_HOST=1.2.3.4 SSH_USER=ubuntu SSH_PASSWORD=secret ``

| Env Var | Description | |---------|-------------| | SSH_HOST | SSH host | | SSH_PORT | SSH port | | SSH_USER | Username | | SSH_PASSWORD | Password | | SSH_KEY | Private key path | | SSH_PASSPHRASE | Key passphrase | | SSH_REMOTE_DIR | Default remote dir | | SSH_WORKSPACE | Local workspace |

3. Config File (ssh-servers.json)

For complex multi-server setups. Looked up in: current directory → package directory.

{
  "servers": [
    {
      "id": "dev",
      "host": "1.2.3.4",
      "username": "ubuntu",
      "password": "secret",
      "workspaces": ["D:\\projects\\my-app"]
    },
    {
      "id": "prod",
      "host": "5.6.7.8",
      "username": "deploy",
      "privateKeyPath": "~/.ssh/id_rsa",
      "workspaces": ["D:\\projects\\production"]
    }
  ]
}

License

AGPL-3.0