antonio-mello-ai/mcp-proxmox

MCP server for managing Proxmox VE clusters through AI assistants like Claude, Cursor, and Cline.
Provision, manage, and monitor your entire Proxmox infrastructure through natural language. Create VMs and containers, manage snapshots, browse storage, and more.
Quick Start
Configuration
Set these environment variables (or create a .env file):
Optional:
Creating a Proxmox API Token
1. Log into your Proxmox web UI
2. Go to **Datacenter** > **Permissions** > **API Tokens**
3. Click **Add** and create a token for your user
4. **Uncheck** "Privilege Separation" for full access, or assign specific permissions:
- VM.Audit — read VM/CT status and config
- VM.PowerMgmt — start/stop/shutdown/reboot
- VM.Snapshot — create/rollback/delete snapshots
- VM.Allocate — create/delete/clone VMs and containers
- VM.Clone — clone operations
- Datastore.Audit — list storages and browse content
- Datastore.AllocateSpace — allocate disk space for new VMs/CTs
- Sys.Audit — read node status and tasks
- VM.Config.Disk — resize disks
- VM.Config.CPU — change CPU allocation
- VM.Config.Memory — change memory allocation
- VM.Monitor — access QEMU monitor (for metrics)
- VM.Console — console interaction tools (screenshots, keyboard input)
- VM.Migrate — migrate VMs/CTs between nodes
- Sys.Modify — manage firewall rules
- VM.Config.Cloudinit — configure cloud-init parameters
Integration
Claude Desktop
Add to ~/.claude/claude_desktop_config.json:
Claude Code
Add to .claude/settings.json or ~/.claude/settings.json:
Cursor
Add to Cursor Settings > MCP with the same configuration as above.
Available Tools
Discovery
| Tool | Description |
|------|-------------|
| list_nodes | List all cluster nodes with CPU, memory, and uptime |
| get_node_status | Detailed node info: CPU model, memory, disk, versions |
| list_vms | List QEMU VMs (filter by node or status) |
| list_containers | List LXC containers (filter by node or status) |
| get_guest_status | Detailed VM/CT status by VMID (auto-detects type and node) |
Lifecycle
| Tool | Description |
|------|-------------|
| start_guest | Start a stopped VM or container |
| stop_guest | Force-stop (requires confirmation) |
| shutdown_guest | Graceful ACPI/init shutdown |
| reboot_guest | Reboot (requires confirmation) |
Storage
| Tool | Description |
|------|-------------|
| list_storages | List storage pools with capacity and usage (filter by node) |
| list_storage_content | Browse ISOs, templates, backups, and disk images |
Provisioning
| Tool | Description |
|------|-------------|
| create_vm | Create a QEMU VM with configurable CPU, memory, disk, ISO, and network |
| create_container | Create an LXC container from a template |
| clone_guest | Clone a VM or CT (full or linked clone, cross-node support) |
| delete_guest | Permanently delete a stopped VM or CT (requires confirmation) |
Backup & Restore
| Tool | Description |
|------|-------------|
| list_backups | List backup files (filter by node, storage, or VMID) |
| create_backup | Create a vzdump backup (snapshot/suspend/stop modes, zstd/lzo/gzip) |
| restore_backup | Restore a VM or CT from a backup file (requires confirmation) |
Command Execution
| Tool | Description |
|------|-------------|
| exec_command | Run a command inside a QEMU VM via guest agent |
> **Note:** exec_command requires qemu-guest-agent installed and running inside the VM. Not supported for LXC containers (Proxmox API limitation).
Console Interaction
| Tool | Description |
|------|-------------|
| vm_screenshot | Capture a PNG screenshot of a QEMU VM's display (login prompt, boot messages, installer, GUI) |
| vm_send_key | Send a key or combination to a VM console (requires confirmation) |
| vm_send_text | Type ASCII text into a VM console (US layout; requires confirmation) |