# Proxmox SSH MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to execute commands on a Proxmox host via SSH.

## Features

- SSH key-based authentication (no passwords in code)
- Built-in security: dangerous commands are blocked
- Single tool: `proxmox_run_host_command`

## Prerequisites

- Node.js 18+
- SSH key pair (`~/.ssh/id_ed25519`)
- Public key added to Proxmox server's `~/.ssh/authorized_keys`

## Installation

```bash
git clone https://github.com/Zaptimist/mcp-proxmox.git
cd mcp-proxmox
npm install
```

## Configuration

Set your Proxmox host via environment variables or edit `index.js`:

**Option 1: Environment variables (recommended)**
```bash
export PROXMOX_HOST=192.168.1.100
export PROXMOX_USER=root
export PROXMOX_PORT=22
export PROXMOX_KEY_PATH=~/.ssh/id_ed25519
```

**Option 2: Edit index.js directly**
```javascript
const sshConfig = {
  host: process.env.PROXMOX_HOST || '192.168.1.100',  // Your Proxmox IP
  username: process.env.PROXMOX_USER || 'root',
  port: parseInt(process.env.PROXMOX_PORT) || 22,
  privateKeyPath: process.env.PROXMOX_KEY_PATH || path.join(os.homedir(), '.ssh', 'id_ed25519')
};
```

### SSH Key Setup

The MCP server will automatically detect if SSH keys are missing or not configured and provide setup instructions. But here's the manual process:

1. Generate a key (if you don't have one):
   ```bash
   ssh-keygen -t ed25519
   ```

2. Copy public key to Proxmox:

   **Windows (PowerShell):**
   ```powershell
   type $env:USERPROFILE\.ssh\id_ed25519.pub | ssh root@YOUR_PROXMOX_IP "mkdir -p ~/.ssh && chmod 700 ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys"
   ```

   **Linux/Mac:**
   ```bash
   ssh-copy-id root@YOUR_PROXMOX_IP
   ```

3. Test the connection:
   ```bash
   ssh root@YOUR_PROXMOX_IP "echo 'SSH key auth works!'"
   ```

If you haven't set up SSH keys yet, the MCP server will return helpful instructions when you try to use it.

## MCP Client Configuration

Add to your MCP client config (e.g., `~/.kiro/settings/mcp.json`):

```json
{
  "mcpServers": {
    "proxmox": {
      "command": "node",
      "args": ["/path/to/mcp-proxmox/index.js"],
      "env": {
        "PROXMOX_HOST": "192.168.1.100"
      },
      "disabled": false,
      "autoApprove": ["proxmox_run_host_command"]
    }
  }
}
```

## Usage

The server exposes one tool:

### `proxmox_run_host_command`

Execute a command on the Proxmox host.

**Input:**
- `command` (string, required): The command to execute

**Example:**
```json
{
  "command": "qm list"
}
```

**Response:**
```json
{
  "success": true,
  "command": "qm list",
  "host": "192.168.1.100",
  "exitCode": 0,
  "stdout": "VMID NAME STATUS MEM(MB) ...",
  "stderr": ""
}
```

## Security

The following commands are blocked for safety:

- VM/Container deletion (`qm destroy`, `pct destroy`)
- File operations (`rm`, `rmdir`, `dd`)
- System operations (`shutdown`, `reboot`, `halt`)
- Package removal (`apt remove`, `apt purge`)
- Service management (`systemctl stop`)
- Storage deletion (`zfs destroy`, `lvremove`)

Destructive actions must be performed manually via the Proxmox web interface.

## License

MIT