ssh-mcp

# SSH MCP Server A Model Context Protocol (MCP) server for executing commands and managing files on remote servers via SSH. Optionally auto-discovers [BinaryLane](https://www.binarylane.com.au/) 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 ```bash npm install npm run build ``` ## Configuration ### Claude Desktop / Claude Code Add to your Claude configuration: ```json { "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`: ```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: ```bash 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 ```bash 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