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:

Config file (highest) — manual connections from ~/.config/ssh-mcp/connections.json
Environment variable — SSH_CONNECTIONS
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

MCP Servers