SSH MCP Server

SSH server management with zero-token SFTP file transfer and SOCKS proxy support

GitHub

@nl4ever/sshmcp

npm version MCP Registry License: MIT

中文文档

Let AI manage your remote servers. A Model Context Protocol (MCP) server that gives AI assistants full SSH access — execute commands, transfer files, manage multiple servers simultaneously, all through natural conversation.

You:   "Deploy the latest build to production server"
AI:    connects → uploads build → restarts service → verifies status

Features

  • 21 Tools — Connect, execute, upload, download, write files, and more
  • Connection Pool — Operate multiple servers simultaneously, each command tagged with server_id
  • Zero-Token File Transfer — SFTP path-based transfer, file content never enters AI context
  • Directory Upload — Auto tar.gz compress → upload → remote decompress (fast for many small files)
  • Async Transfer + Progress — Background transfer for large files with real-time progress tracking
  • Quick Connect — Temporary connections without saving config, returns host:port as temp ID
  • SOCKS4/5 Proxy — Per-connection proxy support
  • Jump Host — SSH ProxyJump for bastion/gateway access
  • Multi-Auth — Password, private key, ssh-agent, keyboard-interactive (OTP/2FA)

Quick Start

Install globally

npm install -g @nl4ever/sshmcp

Add to Claude Code

claude mcp add sshmcp sshmcp

Add to Claude Desktop

Edit claude_desktop_config.json:

{
  "mcpServers": {
    "sshmcp": {
      "command": "npx",
      "args": ["-y", "@nl4ever/sshmcp"]
    }
  }
}

Add to Cursor

Go to Settings → MCP Servers → Add:

{
  "sshmcp": {
    "command": "npx",
    "args": ["-y", "@nl4ever/sshmcp"]
  }
}

Tools Overview

Connection Management

ToolDescription
list_serversList all configured servers and active connections
get_serverView server config details
add_serverAdd/update server config (password, key, agent, OTP)
update_serverModify server config (only pass fields you want to change)
delete_serverRemove a server
rename_serverRename a server ID
connectManually connect (usually not needed, tools auto-connect)
quick_connectTemporary connection, returns host:port as ID
disconnectDisconnect specific server or all connections
test_connectionTest connectivity without affecting existing connections

Command Execution

ToolDescription
executeRun shell commands on remote server (with configurable timeout)

File Operations

ToolDescription
read_fileRead remote file content (with optional line range)
write_fileWrite text content to remote file
upload_fileUpload local file to remote (supports async mode)
upload_directoryUpload directory with auto compress → transfer → decompress
download_fileDownload remote file to local (supports async mode)
download_directoryDownload directory with remote compress → transfer → local decompress
transfer_statusCheck progress of async transfers (size/speed/ETA)

Proxy Management

ToolDescription
list_proxiesList all SOCKS proxy presets
add_proxyAdd SOCKS4/5 proxy preset
delete_proxyRemove a proxy preset

Connection Pool: Multi-Server Operations

All operation tools take a server_id parameter. The connection pool auto-manages connections — no manual connect/disconnect needed:

AI: execute(server_id="prod", command="nginx -s reload")         ← auto-connects to prod
AI: execute(server_id="dev", command="tail -f /var/log/app.log") ← auto-connects to dev, prod stays
AI: execute(server_id="prod", command="curl localhost")           ← reuses prod connection

For temporary servers, use quick_connect which returns host:port as the ID:

AI: quick_connect(host="1.2.3.4", username="root", password="***")
→ "Connected: [email protected]:22, use server_id="1.2.3.4:22""

AI: execute(server_id="1.2.3.4:22", command="df -h")
AI: disconnect(server_id="1.2.3.4:22")

Async Transfer (Large Files)

For large files, enable background transfer mode to avoid blocking:

AI: upload_file(server_id="prod", local_path="big.tar.gz", remote_path="/data/", async_transfer=true)
→ "Background upload started: tf_1"

AI: transfer_status("tf_1")
→ "🔄 Uploading: 638.2 MB / 1.2 GB (53.2%) — 12.4 MB/s, ETA 46s"

AI: transfer_status("tf_1")
→ "✅ Upload complete: 1.2 GB, 98s, 12.3 MB/s"

Small files use synchronous mode by default — no config needed.

Connection Examples

Password authentication

AI: add_server(server_id="prod", name="Production", host="10.0.0.1", username="deploy", password="***")
AI: execute(server_id="prod", command="systemctl status nginx")

Private key authentication

AI: add_server(server_id="aws", name="AWS EC2", host="ec2-xx.compute.amazonaws.com", username="ubuntu", private_key="~/.ssh/id_rsa")

Quick connect (no config saved)

AI: quick_connect(host="192.168.1.100", username="root", password="***")
→ server_id="192.168.1.100:22"

AI: execute(server_id="192.168.1.100:22", command="df -h")
AI: disconnect(server_id="192.168.1.100:22")

Via SOCKS5 proxy

AI: add_proxy(proxy_id="tunnel", name="SSH Tunnel", host="127.0.0.1", port=1080, type="5")
AI: add_server(server_id="internal", ..., proxy="tunnel")

Via jump host

AI: add_server(server_id="bastion", name="Bastion", host="bastion.example.com", username="admin", private_key="~/.ssh/id_rsa")
AI: add_server(server_id="internal", name="Internal DB", host="10.0.0.5", username="dbadmin", password="***", jump_host="bastion")

Config Location

Server and proxy configurations are stored in:

~/.ssh-mcp/config.json

Passwords are stored in plaintext. For production use, prefer private key authentication.

Requirements

  • Node.js >= 18
  • An MCP-compatible client (Claude Code, Claude Desktop, Cursor, etc.)
  • Remote server with SSH access

License

MIT

Serveurs connexes