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

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

Hermes (~/.hermes/config.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