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
git clone https://github.com/bsahane/mcp-proxmox.git
cd mcp-proxmox
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
pip install -r requirements.txt
# (Optional) install the package locally
pip install -e .
.env configuration
- Copy
.env.exampleto.envand edit values:
cp .env.example .env
.env keys:
PROXMOX_API_URL="https://proxmox.example.com:8006"
PROXMOX_TOKEN_ID="root@pam!mcp-proxmox"
PROXMOX_TOKEN_SECRET="<secret>"
PROXMOX_VERIFY="true"
PROXMOX_DEFAULT_NODE="pve"
PROXMOX_DEFAULT_STORAGE="local-lvm"
PROXMOX_DEFAULT_BRIDGE="vmbr0"
Notes:
- Use an API token with appropriate ACLs; for discovery,
PVEAuditorat/is sufficient; for lifecycle, grant narrower roles (e.g.,PVEVMAdmin) on a pool. - Using
.envavoids zsh history expansion issues with!in token IDs.
Run the MCP server (stdio)
Preferred (module form):
source .venv/bin/activate
python -m proxmox_mcp.server
Or installed console script:
source .venv/bin/activate
proxmox-mcp
Configure in Cursor
Edit ~/.cursor/mcp.json (portable example):
{
"mcpServers": {
"proxmox-mcp": {
"command": "python",
"args": ["-m", "proxmox_mcp.server"]
}
}
}
Configure in Claude for Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"proxmox-mcp": {
"command": "python",
"args": ["-m", "proxmox_mcp.server"]
}
}
}
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
vmidorname(+optional node), includes config - Example:
{ "name": "web01" } - Answer:
{ "selector": {...}, "config": {...} }
- Get VM details by
proxmox-list-lxc- List LXC containers (filterable)
- Example:
{ "node": "pve" } - Answer:
[ { "vmid": 50001, "name": "ct01", ... } ]
proxmox-lxc-info- Get LXC details by
vmidorname(+optional node) - Example:
{ "vmid": 50001 } - Answer:
{ "selector": {...}, "config": {...} }
- Get LXC details by
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
- Manage snapshots; rollback supports
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-removeproxmox-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
.envfile. - Name collisions across nodes return clear errors unless you specify
node.
Development
# Lint/type-check as needed (not included by default)
License
MIT