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

### Claude Desktop MCP Configuration

Add the following to your Claude Desktop MCP configuration file:

```json
{
  "tools": [
    {
      "name": "mcpssh",
      "path": "python -m mcpssh",
      "environment": {
        "MCP_SSH_HOSTNAME": "example.com",
        "MCP_SSH_PORT": "22",
        "MCP_SSH_USERNAME": "user",
        "MCP_SSH_KEY_FILENAME": "/path/to/private_key"
      }
    }
  ]
}
```

## Usage

This server implements the Anthropic MCP protocol and provides the following tools:

- `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"
)

# 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