# proxmox-mcp

MCP server for **Proxmox VE 9** — nodes, VMs, LXCs, status, exec. Sibling of `pfsense-mcp`.

## Quick start

```bash
cd ~/Projects/proxmox-mcp
python3 -m venv .venv && .venv/bin/pip install -e .
```

### Cursor (`~/.cursor/mcp.json`)

```json
"proxmox": {
  "command": "/Users/nearxos/Projects/proxmox-mcp/.venv/bin/proxmox-mcp",
  "env": {
    "PROXMOX_VERIFY_SSL": "false",
    "PROXMOX_ALLOW_WRITES": "false",
    "PROXMOX_TARGETS_PATH": "/Users/nearxos/.local/share/proxmox-mcp/targets.json"
  }
}
```

### Connect

```text
proxmox_connect(
  url="https://10.20.30.254:8006",
  token_id="root@pam!cursor",
  token_secret="...",
  name="golden-proxmox"
)
proxmox_test_connection()
proxmox_list_qemu(node="pve")
```

## Tools

| Tool | Description |
|------|-------------|
| `proxmox_connect` / `proxmox_use_target` | Multi-target registry (persisted) |
| `proxmox_test_connection` | Version + nodes |
| `proxmox_list_nodes` | Cluster nodes |
| `proxmox_list_qemu` / `proxmox_list_lxc` | Guest inventory |
| `proxmox_get_qemu_status` / `proxmox_get_lxc_status` | Live status |
| `proxmox_get_qemu_config` | VM config |
| `proxmox_lxc_exec` / `proxmox_qemu_agent_exec` | Guest exec (writes) |
| `proxmox_get_task_log` | Async task output |

## Golden target

Saved as `golden-proxmox` in `~/.local/share/proxmox-mcp/targets.json` (add API token locally).

## License

MIT