Proxmox VE MCP server

proxmox-mcp

Talk to your Proxmox cluster.

An open-source Model Context Protocol server for Proxmox VE. It lets Claude and other AI assistants monitor and manage your nodes, VMs, containers, storage, backups, firewall and more, all from one Docker container.

proxmox-mcp.mattoddie.dev

Quick start · Documentation · Tool reference · Contributing

"Why is the database VM so slow today?"

VM 101 (db) on pve2 has averaged 94% CPU since 09:00, and pve2's IO wait has been above 30% for the same period. Its disk lives on local-lvm, which is 91% full, and last night's backup task to the same disk is still running. Want me to show the backup task's log, or plan a migration of the VM to pve1, which has 40 GiB of free memory?

Ask about your cluster in plain English. The assistant picks from 300+ tools to look things up and, if you allow it, make changes. Some examples:

• 🩺 "Give me a health check of the cluster."
• 📈 "Which VMs use the most memory, and which node has the most headroom?"
• 💾 "Which guests aren't backed up, and did last night's backups succeed?"
• 🧹 "Find snapshots older than a month."
• 🔐 "Review users, API tokens and permissions for anything risky."
• 🚀 "Clone the Debian template into a new VM called web-02 with 4 GB of RAM on VLAN 20."

Highlights

• 🐳 Docker-first. There's one small, distroless image (ghcr.io/mattoddie/proxmox-mcp) for linux/amd64 and linux/arm64. It serves Streamable HTTP for a long-running service, or stdio for docker run -i.
• 🖱️ One-click Claude Desktop install. Each release has an MCP Bundle (.mcpb) for macOS, Windows and Linux: open it and fill in a settings form. No Docker needed.
• 🛡️ Safe by default. The server is read-only unless you turn on writes. Deleting needs a second switch, and running commands inside guests needs a third. Tools that aren't allowed aren't registered at all, destructive tools are labelled so your MCP client asks before running them, every change can be previewed with dry_run and recorded in an audit log, and passwords and keys are redacted from output.
• 🧰 Broad coverage. It covers 19 toolsets: cluster, nodes, VMs, containers, guest agent, snapshots, storage, backups, tasks, access control, firewall, HA, SDN, Ceph, pools, replication, notifications, hardware and a raw API tool.
• ⏱️ Task-aware. Long operations such as starts, clones, migrations and backups run as Proxmox tasks. Tools wait for them and report the result with the end of the task log, or hand back the task ID to follow up later.
• 🎯 Addressed by VMID. Ask about VM 100 and the server finds which node it's on. Single-node installs need no node names at all.
• 🎛️ Tunable. Expose only the toolsets you need, and list tools take search, fields and limit, which keeps the model's context small and focused.
• 🔑 Least privilege. Use a dedicated API token scoped with Proxmox's own roles and ACLs, so Proxmox enforces the limits too.
• 🧪 Tested. The test suite runs against a mock Proxmox API on every build.

Quick start

Shortened. The full README is on GitHub.