mcp-proxmox

MCP server for Proxmox VE API operations over stdio.

Environment Variables

Variable	Default	Description
PVE_URL	—	Proxmox VE API endpoint
PVE_API_TOKEN_ID	—	PVE API token ID (e.g. root@pam!mcp)
PVE_API_TOKEN_SECRET	—	PVE API token secret

Tools

Tool	Description	Required Privileges
cluster_status	Get cluster status (quorum, nodes, version)	Sys.Audit on /
ceph_status	Get Ceph health, OSDs, monitors, PGs	Sys.Audit on /
node_list	List nodes with CPU/memory/disk usage	Sys.Audit on /
vm_list	List all VMs and containers with status	VM.Audit on /vms/{vmid}
vm_status	Get detailed status of a specific VM/CT	VM.Audit on /vms/{vmid}
vm_power	Control VM/CT power (start/stop/restart/suspend/resume/shutdown)	VM.PowerMgmt on /vms/{vmid}
storage_list	List storage pools with type and usage	Datastore.Audit on /storage/{storage}
cluster_resources	Get all cluster resources, optionally filtered by type	Sys.Audit on /
vm_migrate	Migrate a VM to another cluster node	VM.Migrate on /vms/{vmid}

Profile: claptrap

MCP_PROXMOX_PROFILE=claptrap is meant for an automated responder. It exposes all read tools above (without vm_power and vm_migrate) plus these guarded tools:

Tool	Description	Guard	Required Privileges
snapshot_list	Snapshots with age, keep/autosnap markers and what snapshot_cleanup would delete	—	VM.Audit
snapshot_cleanup	Apply the snapshot policy (dry run unless apply=true)	see below	VM.Snapshot
vm_start	Start a stopped guest	not protected, guest is stopped	VM.PowerMgmt
vm_reboot	Graceful reboot	not protected, uptime at least MCP_PROXMOX_MIN_UPTIME	VM.PowerMgmt
vm_reset	Hard reset (QEMU only), last resort	as vm_reboot, and the guest agent no longer answers	VM.PowerMgmt, VM.GuestAgent.Audit

Variable	Default	Description
MCP_PROXMOX_PROFILE	default	default or claptrap
MCP_PROXMOX_PROTECTED	—	Comma separated guest names that never get power actions (short or full name)
MCP_PROXMOX_SNAPSHOT_MAX_AGE	24h	Snapshots older than this are deleted
MCP_PROXMOX_SNAPSHOT_MAX_COUNT	6	Delete until at most this many snapshots remain
MCP_PROXMOX_AUTOSNAP_MARKER	cv4pve-autosnap	Description that marks automatic snapshots
MCP_PROXMOX_MIN_UPTIME	1h	Minimum uptime before vm_reboot / vm_reset (prevents loops)
MCP_PROXMOX_AUDIT_LOG	—	File that every write and every refusal is appended to

Snapshot policy of snapshot_cleanup, in this order:

1. Snapshots with "keep" in name or description are never deleted.
2. Every snapshot older than the max age is deleted, oldest first.
3. While more than the max count remain, the oldest manual snapshots are deleted first; automatic snapshots only as a last resort.

Deletions run one at a time and each waits for its Proxmox task.

The guards are a second layer: give the token only the privileges in the table, and leave out VM.PowerMgmt on protected guests so Proxmox refuses those actions too.

Build

go build -o mcp-proxmox .

Usage

Add to your MCP client config:

{
  "mcpServers": {
    "mcp-proxmox": {
      "command": "/path/to/mcp-proxmox",
      "env": {
        "PVE_URL": "https://pve.example.com:8006",
        "PVE_API_TOKEN_ID": "root@pam!token-name",
        "PVE_API_TOKEN_SECRET": "your-token-secret"
      }
    }
  }
}

The server communicates over stdio using the MCP protocol.