# proxmox-mcp

[MCP](https://modelcontextprotocol.io) server for [Proxmox VE](https://www.proxmox.com) — gives AI assistants read and create access to LXC containers, QEMU VMs, snapshots, and resource pools through the Proxmox API.

## Why

Infrastructure changes (spinning up a new LXC, checking node load, rolling back a snapshot) require cross-referencing the Proxmox UI with whatever task is in flight. This server brings Proxmox state into the conversation, so an AI assistant can inspect and act on the cluster without context-switching to the web UI.

## Tools

**Nodes** — `proxmox_list_nodes`, `proxmox_get_node_status`

**LXC Containers** — `proxmox_list_lxc`, `proxmox_get_lxc_status`, `proxmox_get_lxc_config`, `proxmox_create_lxc`, `proxmox_start_lxc`

**Snapshots** — `proxmox_list_snapshots`, `proxmox_create_snapshot`, `proxmox_restore_snapshot`

**Resource Pools** — `proxmox_list_pools`, `proxmox_assign_pool`

**VMs (read-only)** — `proxmox_list_vms`

Destructive lifecycle operations (stop, destroy) are intentionally not exposed — the server is scoped to inventory, provisioning, and snapshot management only.

## Configuration

| Variable | Default | Description |
|----------|---------|-------------|
| `PROXMOX_HOST` | `192.168.1.215` | Proxmox node IP or hostname |
| `PROXMOX_USER` | `automation@pve` | Proxmox API user |
| `PROXMOX_TOKEN_NAME` | `automation-token` | API token name |
| `PROXMOX_TOKEN_VALUE` | _(required)_ | API token secret |
| `PROXMOX_VERIFY_SSL` | `false` | Set `true` for valid TLS |
| `MCP_TRANSPORT` | `stdio` | `stdio` or `sse` |
| `MCP_HOST` / `MCP_PORT` | `0.0.0.0` / `8000` | SSE listen address |

Authentication uses Proxmox API tokens (not password auth). The token needs `VM.Audit`, `VM.Config.*`, and `Datastore.Audit` privileges on the relevant resource pools.

## Run

```bash
pip install -e .
PROXMOX_TOKEN_VALUE=... proxmox-mcp
```

## Deploy

Deployed as a systemd SSE service on Proteus. GitLab CI pushes on merge to `main`. See `.env.example` for the full variable list.