ssh-mcp-py 0.1.2
A Model Context Protocol for managing and interacting with multiple virtual machines over SSH
License: MIT
Requires Python: >=3.10
Keywords: vm, mcp, llm, automation

# SSH MCP: Model Context Protocol tool for Virtual Machine Management over SSH

SSH MCP is a Model Context Protocol tool written in Python for managing and interacting with multiple virtual machines (VMs) over SSH. It simplifies executing commands on remote servers by using the standard SSH config file format and leverages the robust `paramiko` library to handle SSH connections and command execution securely and efficiently.

-----

## Usage Guide 📖

SSH MCP can be used in two ways: as an MCP server or as a direct command-line tool.

### MCP Server Usage

SSH MCP can also run as an MCP server, providing tools that can be used by AI assistants and other MCP clients:

```bash
uv run ssh-mcp-py
```

**Available MCP Tools:**

1. **execute_ssh_command**: Execute a command on a remote host
   - Parameters: `hostname` (string), `command` (string)

2. **list_ssh_hosts**: List all configured SSH hosts
   - Parameters: None

3. **get_host_info**: Get detailed information about a specific host
   - Parameters: `hostname` (string)

4. **test_ssh_connection**: Test SSH connection to a host
   - Parameters: `hostname` (string)

### Integration with Claude Desktop

To use SSH MCP with Claude Desktop, add the following configuration to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "ssh": {
      "command": "uvx",
      "args": [
        "ssh-mcp-py"
      ],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "SSH_CONFIG_PATH": "/Users/your_username/.ssh/config"
      }
    }
  }
}
```

**Configuration File Location:**

- **macOS**: `/Users/your_username/Library/Application Support/Claude/claude_desktop_config.json`

Replace `your_username` with your actual username

### Direct Command-Line Usage

You can execute commands directly using the command line interface:

**Basic Command Execution**:

```bash
uv run cli.py <host> "<command_to_execute>"
```

**Examples**:

To list the files in the home directory of `web-server-01`:

```bash
uv run cli.py web-server-01 "ls -la ~"
```

To check the disk space on `db-server-01`:

```bash
uv run cli.py db-server-01 "df -h"
```

### MCP Inspector

You can inspect and test the MCP server using the MCP Inspector:

```bash
npx @modelcontextprotocol/inspector uv run ssh-mcp-py -e SSH_CONFIG_PATH=/Users/your_username/.ssh/config -e PROXY_CONFIG_PATH=/config/proxy.json
```

This will open a web interface where you can test the available MCP tools interactively.

-----

## Key Features 🚀

- **Standard SSH Config**: Uses the familiar `~/.ssh/config` file format for managing VM connection details
- **Automatic Key Management**: Uses SSH keys specified in the config file for each host
- **Remote Command Execution**: Execute terminal commands on any configured VM directly from your local machine
- **MCP Integration**: Provides tools for AI assistants through the Model Context Protocol
- **Simplified Workflow**: Streamline your server administration tasks using standard SSH configuration

-----

## Requirements 📋

To use SSH MCP, you'll need the following on your system:

- **Python 3.10 or higher**: Ensure you have a recent version of Python installed.
- **paramiko**: The core Python library for the SSHv2 protocol.
- **fastmcp**: For MCP server functionality.

-----

## Configuration ⚙️

SSH MCP uses the standard SSH configuration file format. By default, it looks for `~/.ssh/config`, but you can specify a custom path using the `SSH_CONFIG_PATH` environment variable.

### SSH Config File Setup

Create or update your `~/.ssh/config` file with your server details:

**Example `~/.ssh/config`:**

```config
Host web-server-01
    HostName 192.168.1.101
    Port 22
    User admin
    IdentityFile ~/.ssh/id_rsa

Host db-server-01
    HostName 192.168.1.102
    Port 22
    User dba
    IdentityFile ~/.ssh/id_rsa

Host app-server-01
    HostName 192.168.1.103
    Port 2222
    User deployer
    IdentityFile ~/.ssh/id_ed25519
```

### Proxy Configuration (Optional)

SSH MCP supports SOCKS5 proxy connections with authentication. Create a JSON file with proxy configurations and set the `PROXY_CONFIG_PATH` environment variable:

**Example `proxy_config.json`:**

```json
{
  "vm-a": {
    "host": "proxy.example.com",
    "port": 1080,
    "username": "proxy_user",
    "password": "proxy_pass"
  },
  "vm-b": {
    "host": "another-proxy.example.com",
    "port": 1080,
    "username": "another_user",
    "password": "another_pass"
  }
}
```

When a host is configured in both SSH config and proxy config, SSH MCP will automatically use the SOCKS5 proxy for that connection.

### Environment Variables (Optional)

- `MCP_TRANSPORT`: stdio, sse, streamable-http (defaults to stdio)
- `SSH_CONFIG_PATH`: Path to SSH config file (defaults to `~/.ssh/config`)
- `PROXY_CONFIG_PATH`: Path to JSON file containing SOCKS5 proxy configurations (optional)

-----

## Architecture & Workflow 🏗️

SSH MCP follows a clean architecture with clear separation between configuration management, SSH operations, and MCP integration.

### Class Structure

```mermaid
classDiagram
    class SSHConfig {
        +config_file_path: str
        +ssh_config: paramiko.SSHConfig
        +__init__()
        +_load_ssh_config() paramiko.SSHConfig
        +get_host_config(hostname) Dict
        +list_hosts() List[str]
    }
    
    class SSHClient {
        +config: SSHConfig
        +__init__(config)
        +execute_command(hostname, command) Dict
        +list_hosts() List[str]
    }
    
    class MCPTools {
        +execute_ssh_command(hostname, command) str
        +list_ssh_hosts() str
        +get_host_info(hostname) str
        +test_ssh_connection(hostname) str
    }
    
    SSHClient --> SSHConfig : uses
    MCPTools --> SSHClient : uses
    SSHConfig --> paramiko.SSHConfig : wraps
```

### Workflow Diagram

```mermaid
graph TD
    A[MCP Client Request] --> B{Tool Type}
    B -->|execute_ssh_command| C[execute_ssh_command]
    B -->|list_ssh_hosts| D[list_ssh_hosts]
    B -->|get_host_info| E[get_host_info]
    B -->|test_ssh_connection| F[test_ssh_connection]
    
    C --> G[get_ssh_client]
    D --> G
    E --> G
    F --> G
    
    G --> H[SSHClient.__init__]
    H --> I[SSHConfig.__init__]
    I --> J[_load_ssh_config]
    J --> K[paramiko.SSHConfig.parse]
    
    C --> L[SSHClient.execute_command]
    L --> M[get_host_config]
    M --> N[paramiko.SSHConfig.lookup]
    N --> O[paramiko.SSHClient.connect]
    O --> P[paramiko.SSHClient.exec_command]
    
    D --> Q[SSHConfig.list_hosts]
    Q --> R[paramiko.SSHConfig.get_hostnames]
    
    E --> M
    F --> M
    F --> S[paramiko.SSHClient.connect]
```

-----

## Development & Testing 🧪

### Clone code and setup 💻

1. **Clone the Repository**: Start by cloning the SSH MCP repository to your local machine
2. **Install Dependencies**: Install the necessary Python libraries `uv sync`
3. **Setup Pre-commit**: Run `uv run pre-commit install`. This will automatically run code quality checks before each commit, catching issues early and maintaining consistent code standards.

### Test Structure

SSH MCP uses a focused testing approach that emphasizes real integration tests over complex mocked unit tests.

- **`tests/test_ssh_client.py`**: Basic unit tests for core functionality
- **`tests/test_mcp.py`**: Minimal MCP tool tests with simple mocking
- **`tests/test_integration.py`**: Real integration tests that connect to actual SSH hosts

### Integration Testing Setup

The integration tests require a host named `test` in your SSH config. Add a host like this to `~/.ssh/config`:

```config
Host test
    HostName your-test-server.com
    User your-username
    IdentityFile ~/.ssh/your-key
```

The integration tests will:

- Connect to the real SSH host
- Execute actual Linux commands
- Test the full MCP workflow end-to-end

### Running Tests

```bash
# Run all tests
uv run pytest tests/ -v

# Run only integration tests (requires 'test' host)
uv run pytest tests/test_integration.py -v

# Run only unit tests
uv run pytest tests/test_ssh_client.py tests/test_mcp.py -v

# Run with coverage
uv run pytest tests/ --cov=ssh_mcp --cov-report=html
```

### Code Quality

The project uses `ruff` for linting and formatting:

```bash
uv run ruff check .
uv run ruff format .
```

### Publishing to PyPI

To publish this package to PyPI, bump the version in pyproject.toml and run:

```bash
rm -rf dist
uv build
uv publish --username __token__ --password YOUR_PYPI_API_KEY
```

Replace `YOUR_PYPI_API_KEY` with your actual PyPI API token.