Provides comprehensive management of Proxmox Virtual Environment infrastructure, including VM/LXC lifecycle operations, storage management, networking configuration, snapshots, backups, user permissions, and cluster monitoring through the Proxmox API.
MCP Proxmox Server
Advanced Proxmox Model Context Protocol (MCP) server in Python exposing rich Proxmox utilities for discovery, lifecycle, networking, snapshots/backups, metrics, pools/permissions, and orchestration.
Guide reference: MCP Quickstart (Python)
Structure mirrors:
bsahane/mcp-ansible
Quick start
.env configuration
Copy
.env.example
to.env
and edit values:
.env
keys:
Notes:
Use an API token with appropriate ACLs; for discovery,
PVEAuditor
at/
is sufficient; for lifecycle, grant narrower roles (e.g.,PVEVMAdmin
) on a pool.Using
.env
avoids zsh history expansion issues with!
in token IDs.
Run the MCP server (stdio)
Preferred (module form):
Or installed console script:
Configure in Cursor
Edit ~/.cursor/mcp.json
(portable example):
Configure in Claude for Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json
:
Tools reference
All tools are available via MCP. Destructive tools accept confirm
, and most write operations support dry_run
, wait
, timeout
, poll_interval
.
Format below per tool:
Description
Example question → Possible answer (shape)
Core discovery
proxmox-list-nodes
List cluster nodes (name, status, CPU/RAM/disk summary)
Example: "List cluster nodes"
Answer:
[ { "node": "pve", "status": "online", ... } ]
proxmox-node-status
Detailed node health (load, uptime, versions)
Example:
{ "node": "pve" }
Answer:
{ "kversion": "...", "uptime": 123456, ... }
proxmox-list-vms
List VMs (filter by node, status, name substring)
Example:
{ "node": "pve", "status": "running" }
Answer:
[ { "vmid": 100, "name": "web01", ... } ]
proxmox-vm-info
Get VM details by
vmid
orname
(+optional node), includes configExample:
{ "name": "web01" }
Answer:
{ "selector": {...}, "config": {...} }
proxmox-list-lxc
List LXC containers (filterable)
Example:
{ "node": "pve" }
Answer:
[ { "vmid": 50001, "name": "ct01", ... } ]
proxmox-lxc-info
Get LXC details by
vmid
orname
(+optional node)Example:
{ "vmid": 50001 }
Answer:
{ "selector": {...}, "config": {...} }
proxmox-list-storage
List storages (types, free/used)
Example:
{}
Answer:
[ { "storage": "local-lvm", "type": "lvmthin", ... } ]
proxmox-storage-content
List storage content (ISOs, templates, images)
Example:
{ "node": "pve", "storage": "local" }
Answer:
[ { "volid": "local:iso/foo.iso", ... } ]
proxmox-list-bridges
List node bridges (vmbr...)
Example:
{ "node": "pve" }
Answer:
[ { "iface": "vmbr0", ... } ]
proxmox-list-tasks
Recent tasks (filter by node, user)
Example:
{ "node": "pve", "limit": 20 }
Answer:
[ { "upid": "UPID:...", "status": "OK" }, ... ]
proxmox-task-status
Check a task status
Example:
{ "upid": "UPID:..." }
Answer:
{ "status": "stopped", "exitstatus": "OK" }
VM lifecycle
proxmox-clone-vm
Clone template VM to new VMID/name (supports target node, storage)
Example:
{ "source_vmid": 101, "new_vmid": 50009, "name": "web01", "storage": "local-lvm", "confirm": true, "wait": true }
Answer:
{ "upid": "UPID:...", "status": {...} }
proxmox-create-vm
Create new VM from ISO/template (minimal config)
Example:
{ "node": "pve", "vmid": 200, "name": "web02", "iso": "debian.iso", "confirm": true }
Answer:
{ "upid": "UPID:..." }
proxmox-delete-vm
Delete VM (confirm, purge)
Example:
{ "name": "web01", "purge": true, "confirm": true }
Answer:
{ "upid": "UPID:..." }
proxmox-start-vm
/proxmox-stop-vm
/proxmox-reboot-vm
/proxmox-shutdown-vm
Manage power state (stop supports hard and timeout)
Example:
{ "name": "web01", "wait": true }
Answer:
{ "upid": "UPID:...", "status": {...} }
proxmox-migrate-vm
Live/offline migrate to another node
Example:
{ "name": "web01", "target_node": "pve2", "live": true }
Answer:
{ "upid": "UPID:..." }
proxmox-resize-vm-disk
Grow disk (GB) on target disk (e.g., scsi0)
Example:
{ "name": "web01", "disk": "scsi0", "grow_gb": 10, "confirm": true, "wait": true }
Answer:
{ "upid": "UPID:...", "status": {...} }
proxmox-configure-vm
Set whitelisted params (cores, memory, balloon, netX, agent, etc.)
Example:
{ "name": "web01", "params": { "memory": 4096, "cores": 4 }, "confirm": true }
Answer:
{ "upid": "UPID:..." }
or{ "result": null }
LXC lifecycle
proxmox-create-lxc
Create container from template (CPU/mem, rootfs size, net, storage)
Example:
{ "node": "pve", "vmid": 50050, "hostname": "ct01", "ostemplate": "debian-12.tar.zst", "confirm": true }
Answer:
{ "upid": "UPID:..." }
proxmox-delete-lxc
/proxmox-start-lxc
/proxmox-stop-lxc
/proxmox-configure-lxc
Manage container lifecycle and config
Cloud-init & networking
proxmox-cloudinit-set
Set CI params (ipconfig0, sshkeys, ciuser/cipassword)
Example:
{ "name": "web01", "ipconfig0": "ip=192.168.1.50/24,gw=192.168.1.1", "confirm": true }
Answer:
{ "upid": "UPID:..." }
or{ "result": null }
proxmox-vm-nic-add
/proxmox-vm-nic-remove
Add/remove NICs (bridge, model, VLAN)
proxmox-vm-firewall-get
/proxmox-vm-firewall-set
Get/set per-VM firewall state and rules
Images, templates, snapshots, backups
proxmox-upload-iso
/proxmox-upload-template
Upload ISO or LXC template to storage
proxmox-template-vm
Convert VM to template
proxmox-list-snapshots
/proxmox-create-snapshot
/proxmox-delete-snapshot
/proxmox-rollback-snapshot
Manage snapshots; rollback supports
wait
proxmox-backup-vm
/proxmox-restore-vm
Run vzdump and restore archives
Metrics and monitoring
proxmox-vm-metrics
RRD metrics for VM (timeframe, cf)
proxmox-node-metrics
RRD metrics for node
Pools, users, permissions
proxmox-list-pools
/proxmox-create-pool
/proxmox-delete-pool
/proxmox-pool-add
/proxmox-pool-remove
proxmox-list-users
/proxmox-list-roles
/proxmox-assign-permission
Orchestration helpers
proxmox-wait-task
Poll a task until done/timeout
proxmox-register-vm-as-host
Emit JSON/INI snippet for Ansible inventory (hostname, IP, SSH user/key)
proxmox-guest-exec
(optional)Run a command via QEMU Guest Agent (requires agent in guest)
Examples
List nodes:
{}
forproxmox-list-nodes
VMs on node
pve
:{ "node": "pve" }
forproxmox-list-vms
Clone a template:
{ "source_vmid": 101, "new_vmid": 50009, "name": "web01", "storage": "local-lvm", "confirm": true, "wait": true }
Configure Cloud-init IP:
{ "name": "web01", "ipconfig0": "ip=192.168.1.50/24,gw=192.168.1.1", "confirm": true }
Notes
Server uses stdio transport; prints only MCP protocol to stdout. Logs go to stderr.
Authentication uses your environment variables and/or
.env
file.Name collisions across nodes return clear errors unless you specify
node
.
Development
License
MIT
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Enables comprehensive management of Proxmox virtualization infrastructure through natural language, supporting VM/LXC lifecycle operations, networking, snapshots, backups, metrics monitoring, and cluster orchestration. Provides full access to Proxmox API functionality including resource discovery, cloud-init configuration, and automated deployment workflows.
Related MCP Servers
- -securityAlicense-qualityA Python-based server enabling interaction with Proxmox hypervisors. It supports secure authentication and provides tools for managing nodes, VMs, clusters, and storage.Last updated -153MIT License
- -securityAlicense-qualityAn enhanced Python-based MCP server that enables complete VM lifecycle management and monitoring of Proxmox virtualization platforms through natural language, with 11 REST API endpoints for seamless integration.Last updated -12MIT License
- -securityAlicense-qualityA Python-based Model Context Protocol server that enables managing Proxmox virtualization platform through Cursor IDE, supporting complete VM lifecycle management including creation, power control, and deletion.Last updated -9MIT License
- AsecurityAlicenseAqualityProvides seamless integration between AI assistants and Prometheus, enabling natural language interactions with your monitoring infrastructure. This server allows for effortless querying, discovery, and analysis of metrics.Last updated -104121MIT License