# Custom Proxmox MCP Server

A robust, maintenance-free Model Context Protocol (MCP) server for Proxmox VE with **multi-cluster support**.

## Features

- **Multi-Cluster:** Manage multiple Proxmox clusters from a single container
- **Hybrid Approach:** Curated high-level tools + raw API access for 100% coverage
- **Zero Maintenance:** Raw API tool works with any Proxmox feature without code changes

## Tools

| Tool | Description |
|------|-------------|
| `list_clusters` | Lists all configured Proxmox clusters |
| `list_nodes` | Lists nodes in a cluster |
| `get_cluster_resources` | Gets VMs, LXCs, and storage summary |
| `proxmox_api_call` | Execute any Proxmox API call directly |

All tools accept a `cluster` parameter. If only one cluster is configured, it's optional.

## Configuration

### 1. Create `clusters.json`

```json
{
  "clusters": {
    "production": {
      "url": "pve-prod.example.io:8006",
      "user": "mcp@pam",
      "token_id": "token",
      "token_secret": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "verify_ssl": false
    },
    "homelab": {
      "url": "pve-home.local:8006",
      "user": "root@pam",
      "token_id": "mcp",
      "token_secret": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
      "verify_ssl": false
    }
  }
}
```

> **Token Format:** If your full token is `user@pam!mytoken`, set `user: "user@pam"` and `token_id: "mytoken"`

### 2. Deploy with Docker Compose

```yaml
services:
  proxmox-mcp:
    image: gitea.ext.ben.io/b3nw/proxmox-mcp-custom:latest
    environment:
      - MCP_ALLOWED_HOSTS=proxmox-mcp.example.io,localhost:*
    volumes:
      - ./clusters.json:/app/clusters.json:ro
    ports:
      - "8000:8000"
    restart: unless-stopped
```

### 3. Connect MCP Client

SSE endpoint: `https://your-host/sse`

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `MCP_ALLOWED_HOSTS` | `localhost:*,127.0.0.1:*` | Allowed Host headers |
| `CLUSTERS_CONFIG_PATH` | `/app/clusters.json` | Path to clusters config |

## Local Development

```bash
# Setup
cp clusters.json.example clusters.json
# Edit clusters.json with your credentials

# Build and run
make build
make dev

# Test
make logs
make test-sse
make stop
```

## Tech Stack

- Python 3.11+ / FastMCP / proxmoxer
- SSE transport / uvicorn
- Docker with multi-stage build