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:

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:

{
  "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:

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

Examples:

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

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

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

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

MCP Inspector

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

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:

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:

{
  "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.

Command Logging

Every execute_ssh_command call writes a log file containing the command and its full, untruncated stdout/stderr (plus host, exit code, and duration). The response includes the path to that log file, so even when the response output is truncated to max_length, the complete output is preserved on disk.

The log directory is controlled by the SSH_MCP_LOG_DIR environment variable. When unset, an OS-appropriate default is used:

OS	Default log directory
macOS	~/Library/Logs/ssh-mcp/
Linux	${XDG_STATE_HOME:-~/.local/state}/ssh-mcp/logs/
Windows	%LOCALAPPDATA%\ssh-mcp\logs\

• Set SSH_MCP_LOG_DIR to a directory path to use a custom location.
• Set SSH_MCP_LOG_DIR=false to disable logging entirely (no log file is written and no log path is returned).
• If the log directory cannot be created or written, the command still runs and returns its output; the response notes that logging was skipped.
• One log file is created per command. Cleanup is up to you — SSH MCP does not rotate or delete old logs.

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)
• SSH_MCP_LOG_DIR: Directory for per-command log files (defaults to an OS-specific path; set to false to disable logging)

---

Architecture & Workflow 🏗️

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

Class Structure

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

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:

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

# 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:

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:

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.