4.3 KiB

Raw Blame History

MCP SSH Server

An Anthropic Model Context Protocol (MCP) server that provides SSH access to remote systems, enabling full access to remote virtual machines in a sandbox environment.

Features

Uses stdio for MCP communication
Provides SSH connection to remote servers
Enables command execution on remote systems
Secure public key authentication
Configurable via environment variables or MCP config

Installation

pip install -e .

Configuration

The SSH server can be configured using environment variables or the MCP JSON configuration:

Environment Variable	Description	Default
`MCP_SSH_HOSTNAME`	SSH server hostname or IP address	None
`MCP_SSH_PORT`	SSH server port	22
`MCP_SSH_USERNAME`	SSH username	None
`MCP_SSH_KEY_FILENAME`	Path to SSH private key file	None
`MCP_SSH_SERVER_NAME`	Custom name for the server instance	"SSH Server"
`MCP_SSH_TOOL_PREFIX`	Prefix for tool names (e.g., 'server1_' for 'server1_ssh_connect')	""

Claude Desktop MCP Configuration

Add the following to your Claude Desktop MCP configuration file:

{
  "mcpssh": {
    "command": "python",
    "args": [
      "-m",
      "mcpssh"
    ],
    "env": {
      "MCP_SSH_HOSTNAME": "example.com",
      "MCP_SSH_PORT": "22",
      "MCP_SSH_USERNAME": "user",
      "MCP_SSH_KEY_FILENAME": "/path/to/private_key"
    }
  }
}

Multiple SSH Server Configuration

You can configure multiple SSH servers in Claude Desktop by creating multiple entries with different names and using the MCP_SSH_SERVER_NAME and MCP_SSH_TOOL_PREFIX environment variables to distinguish them:

{
  "mcpssh1": {
    "command": "python",
    "args": [
      "-m",
      "mcpssh"
    ],
    "env": {
      "MCP_SSH_HOSTNAME": "production.example.com",
      "MCP_SSH_USERNAME": "prod-user",
      "MCP_SSH_KEY_FILENAME": "~/.ssh/prod_key",
      "MCP_SSH_SERVER_NAME": "Production Server",
      "MCP_SSH_TOOL_PREFIX": "prod_"
    }
  },
  "mcpssh2": {
    "command": "python",
    "args": [
      "-m",
      "mcpssh"
    ],
    "env": {
      "MCP_SSH_HOSTNAME": "dev.example.com",
      "MCP_SSH_USERNAME": "dev-user",
      "MCP_SSH_KEY_FILENAME": "~/.ssh/dev_key",
      "MCP_SSH_SERVER_NAME": "Development Server",
      "MCP_SSH_TOOL_PREFIX": "dev_"
    }
  }
}

With this configuration:

Claude will have access to two separate SSH server tools
Each server will be identified by its custom name in Claude's UI
Each server's tools will have unique prefixes to distinguish them (e.g., prod_ssh_connect vs dev_ssh_connect)

Usage

This server implements the Anthropic MCP protocol and provides the following tools (note that when using MCP_SSH_TOOL_PREFIX, the tool names will be prefixed with that value):

ssh_connect: Connect to an SSH server using public key authentication (using config or explicit parameters)
ssh_execute: Execute a command on the SSH server
ssh_disconnect: Disconnect from the SSH server

Example

from mcp import ClientSession, StdioServerParameters
from mcpssh.server import SSHServerMCP

# Start the server in a subprocess
server_params = StdioServerParameters(
    command="python",
    args=["-m", "mcpssh"],
    env={
        "MCP_SSH_HOSTNAME": "example.com",
        "MCP_SSH_PORT": "22",
        "MCP_SSH_USERNAME": "user",
        "MCP_SSH_KEY_FILENAME": "/path/to/private_key"
    }
)

# Use with an MCP client
with ClientSession(server_params) as client:
    # Connect to SSH server
    client.ssh_connect()
    
    # Execute a command
    result = client.ssh_execute(command="ls -la")
    print(result["stdout"])
    
    # Disconnect
    client.ssh_disconnect()

Direct Server Usage

from mcpssh.server import SSHServerMCP

# Initialize and run the server
server = SSHServerMCP(
    hostname="example.com",
    port=22,
    username="user",
    key_filename="/path/to/private_key",
    server_name="My Custom Server",  # Optional custom server name
    tool_prefix="custom_"           # Optional tool name prefix
)

# Run the server with stdio transport
server.run(transport="stdio")

Security Note

This tool provides full access to a remote system. It should only be used with virtual machines in sandbox environments where security implications are well understood.

License

MIT

4.3 KiB Raw Blame History