feat: v1.2.0 — deploy, lifecycle, discovery

- New: proxmox_create_lxc, proxmox_create_qemu (deploy)
- New: proxmox_start_vm, stop_vm, shutdown_vm, reboot_vm (lifecycle)
- New: proxmox_delete_vm, proxmox_clone_vm
- New: proxmox_list_storage, proxmox_list_templates (discovery)
- New: proxmox_get_next_vmid, proxmox_get_lxc_config
- Fix: LXC config parity with QEMU (get_lxc_config)
- Bump: 1.0.0 → 1.2.0 (29 tools, up from 17)
This commit is contained in:
root
2026-06-17 06:37:41 +00:00
parent 2e59fb5af2
commit 2e371b2709
7 changed files with 319 additions and 30 deletions

105
README.md
View File

@@ -1,6 +1,6 @@
# proxmox-mcp
# proxmox-mcp v1.2.0
MCP server for **Proxmox VE 9** — nodes, VMs, LXCs, status, exec. Sibling of `pfsense-mcp`.
MCP server for **Proxmox VE** — nodes, VMs, LXCs, status, exec, **deploy, lifecycle, and discovery**. Sibling of `pfsense-mcp`.
## Quick start
@@ -9,48 +9,103 @@ cd ~/Projects/proxmox-mcp
python3 -m venv .venv && .venv/bin/pip install -e .
```
### Cursor (`~/.cursor/mcp.json`)
### Hermes (`~/.hermes/config.yaml`)
```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"
}
}
```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
```text
proxmox_connect(
url="https://10.20.30.254:8006",
token_id="root@pam!cursor",
token_secret="...",
name="golden-proxmox"
)
```
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="pve")
proxmox_list_qemu(node="dell")
```
## Tools
## 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` | VM config |
| `proxmox_lxc_exec` / `proxmox_qemu_agent_exec` | Guest exec (writes) |
| `proxmox_get_task_log` | Async task output |
| `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 `golden-proxmox` in `~/.local/share/proxmox-mcp/targets.json` (add API token locally).
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