# 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

```bash
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:

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

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

1. Claude will have access to two separate SSH server tools
2. Each server will be identified by its custom name in Claude's UI
3. 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

```python
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

```python
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