SSH MCP Server

A Model Context Protocol (MCP) server for executing commands and managing files on remote servers via SSH.

Optionally auto-discovers BinaryLane VPS servers so they're available immediately.

Features

• Execute shell commands on remote servers
• Read files and list directories remotely
• Upload and download files via SFTP
• Persistent connections saved to config file across restarts
• BinaryLane auto-discovery of active servers
• Per-connection SSH key configuration
• Multiple connection sources with clear priority

Installation

npm install
npm run build

Configuration

Claude Desktop / Claude Code

Add to your Claude configuration:

{
  "mcpServers": {
    "ssh": {
      "command": "node",
      "args": ["/path/to/ssh-mcp/dist/index.js"],
      "env": {
        "BINARYLANE_API_TOKEN": "your-token-here"
      }
    }
  }
}

The BINARYLANE_API_TOKEN is optional — only needed for auto-discovery of BinaryLane servers.

Config File

On first run, a config file is created at ~/.config/ssh-mcp/connections.json:

{
  "defaultPrivateKeyPath": "~/.ssh/id_ed25519",
  "binarylane": {
    "enabled": true,
    "apiToken": "your-token-here",
    "defaultUsername": "root",
    "defaultPrivateKeyPath": "~/.ssh/id_ed25519"
  },
  "connections": [
    {
      "name": "my-server",
      "host": "10.0.0.5",
      "port": 22,
      "username": "deploy",
      "privateKeyPath": "~/.ssh/deploy_key"
    }
  ]
}

The BinaryLane API token can be set here or as an environment variable.

Environment Variable (Legacy)

Still supported for backward compatibility:

export SSH_CONNECTIONS='[
  {"name": "web1", "host": "192.168.1.10", "port": 22, "username": "root", "privateKeyPath": "~/.ssh/id_rsa"}
]'

Connection Options

Option	Required	Default	Description
name	Yes	-	Unique identifier for the connection
host	Yes	-	Server hostname or IP address
port	No	22	SSH port
username	Yes	-	SSH username
privateKeyPath	No	-	Path to SSH private key (supports ~ expansion)
password	No	-	SSH password (if not using key auth)

If neither privateKeyPath nor password is provided, the server will try default SSH key locations (~/.ssh/id_ed25519, ~/.ssh/id_rsa).

Connection Priority

When multiple sources define the same connection name:

1. Config file (highest) — manual connections from ~/.config/ssh-mcp/connections.json
2. Environment variable — SSH_CONNECTIONS
3. BinaryLane auto-discovery (lowest) — active servers from the API

Available Tools

Connection Management

• list_connections — List all available SSH connections with source info
• test_connection — Test connectivity with latency reporting
• add_connection — Add a connection (persisted to config file)
• remove_connection — Remove a manual connection from config
• refresh_connections — Re-discover BinaryLane servers and reload all connections
• get_config — Show current configuration (tokens redacted)

Command Execution

• run_command — Execute a shell command with configurable timeout

File Operations

• read_remote_file — Read file contents via SFTP
• list_remote_directory — List directory contents with metadata
• upload_file — Upload a local file to remote server
• download_file — Download a remote file to local machine

Example Usage

# List all connections (shows source: config, env, or binarylane)
list_connections

# Test connection
test_connection connection="web1"

# Run a command
run_command connection="web1" command="uptime"

# Add a new persistent connection
add_connection name="staging" host="10.0.0.5" username="deploy" privateKeyPath="~/.ssh/deploy_key"

# Refresh after creating new BinaryLane servers
refresh_connections

Security Notes

• SSH keys are read from your local filesystem and never transmitted or stored by the MCP
• Passwords in config are only held in memory during operation
• The config file should be protected with appropriate filesystem permissions
• Commands are executed with the privileges of the SSH user
• Consider using dedicated SSH keys with limited permissions for automation

Development

npm run dev    # Watch mode
npm run build  # Compile TypeScript
npm start      # Run compiled server

Project Structure

ssh-mcp/
├── src/
│   ├── index.ts        # Server entry point
│   ├── ssh-client.ts   # SSH connection manager
│   ├── config.ts       # Persistent config file management
│   ├── binarylane.ts   # BinaryLane auto-discovery
│   ├── tools.ts        # MCP tool definitions
│   └── handlers.ts     # Tool handler implementations
├── dist/               # Compiled JavaScript
├── package.json
└── tsconfig.json

License

MIT