# 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
