# proxmox-mcp v1.2.0

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

## Quick start

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

### Hermes (`~/.hermes/config.yaml`)

```yaml
mcp_servers:
  proxmox:
    command: /usr/local/lib/hermes-agent/venv/bin/proxmox-mcp
    timeout: 120
    enabled: true
    env:
      PROXMOX_VERIFY_SSL: 'false'
      PROXMOX_ALLOW_WRITES: 'true'
```

### Connect

```
proxmox_connect(url="https://10.77.30.5:8006", token_id="root@pam!tokenname", token_secret="...", name="dell")
proxmox_test_connection()
proxmox_list_qemu(node="dell")
```

## Tools (30 total)

### Connection & Discovery
| Tool | Description |
|------|-------------|
| `proxmox_connect` / `proxmox_use_target` | Multi-target registry (persisted) |
| `proxmox_list_targets` / `proxmox_disconnect_target` | Target management |
| `proxmox_get_config` | Server config and active target |
| `proxmox_test_connection` | Version + nodes |

### Nodes & Cluster
| Tool | Description |
|------|-------------|
| `proxmox_list_nodes` | Cluster nodes |
| `proxmox_get_node_status` | Node resource status |
| `proxmox_get_next_vmid` | Next available VMID from cluster |

### Storage & Templates
| Tool | Description |
|------|-------------|
| `proxmox_list_storage` | Storage pools with usage stats |
| `proxmox_list_templates` | Templates and ISOs on a storage pool |

### Guests — Read
| Tool | Description |
|------|-------------|
| `proxmox_list_qemu` / `proxmox_list_lxc` | Guest inventory |
| `proxmox_get_qemu_status` / `proxmox_get_lxc_status` | Live status |
| `proxmox_get_qemu_config` / `proxmox_get_lxc_config` | Full config |

### Guests — Lifecycle (requires `PROXMOX_ALLOW_WRITES=true`)
| Tool | Description |
|------|-------------|
| `proxmox_start_vm` | Start a stopped VM/LXC |
| `proxmox_stop_vm` | Force stop a VM/LXC |
| `proxmox_shutdown_vm` | Graceful ACPI shutdown |
| `proxmox_reboot_vm` | Reboot a VM/LXC |
| `proxmox_lxc_exec` | Execute command inside an LXC |
| `proxmox_qemu_agent_exec` | Execute via QEMU guest agent |

### Guests — Deploy (requires `PROXMOX_ALLOW_WRITES=true`)
| Tool | Description |
|------|-------------|
| `proxmox_create_lxc` | Create a new LXC container |
| `proxmox_create_qemu` | Create a new QEMU VM |
| `proxmox_delete_vm` | Delete a VM/LXC (purge option) |
| `proxmox_clone_vm` | Clone a VM/LXC to new VMID |

### Tasks
| Tool | Description |
|------|-------------|
| `proxmox_get_task_status` | Async task status |
| `proxmox_get_task_log` | Async task log output |

## Golden target

Saved as `dell` in `~/.local/share/proxmox-mcp/targets.json` — Dell Proxmox at `10.77.30.5:8006`.

## Safety

- `PROXMOX_ALLOW_WRITES=false` by default
- All lifecycle/deploy tools require writes enabled
- Delete requires explicit `purge=true` to destroy data
- Token secrets stored with `chmod 600` in targets.json

## Changelog

### v1.2.0
- **New:** LXC create, QEMU create, delete, clone
- **New:** Start, stop, shutdown, reboot lifecycle tools
- **New:** Storage listing, template/ISO discovery
- **New:** `proxmox_get_next_vmid`, `proxmox_get_lxc_config`
- **Fix:** Config parity — LXC config now matches QEMU

### v1.0.0
- Initial release — read-only Proxmox API + exec

## License

MIT