Proxmox VE MCP server
You can inspect Proxmox VE and safely perform confirmation-gated guest power and snapshot actions from chat.
View nodes, storage use, running/stopped guest counts, and backup jobs.
Find VMs and containers by name, ID, tag, kind, or status, with current CPU/memory/uptime.
Get one guest’s details: resources, disks, notes, snapshots, last backup, backup-job coverage, and recent tasks.
Surface attention items: guests with no backup job, overdue backups, stopped production guests, old snapshots, filling storage, and high memory use.
Start, cleanly shut down, or reboot a VM/container after a one-time confirmation code.
Take a snapshot with a description after confirmation.
Safety limits: no delete, restore, or snapshot rollback tools; changes require confirmation and are recorded in Proxmox’s task log.
Connects to a Proxmox VE 8 or 9 cluster through its REST API using an API token, letting users query nodes, storage, guests and backup jobs, inspect individual VMs and containers (disks, notes, snapshots, last backup, coverage by backup jobs, recent tasks), and surface problems such as guests with no backup job, overdue backups, stopped production guests, old snapshots, filling storage and memory-short guests. Also allows starting, cleanly shutting down and rebooting guests and taking snapshots, with a one-time confirmation code required before any change is applied. No tool deletes guests, restores backups or rolls back snapshots.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Proxmox VE MCP server which guests aren't covered by any backup job?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Proxmox VE MCP server
Ask Claude about your Proxmox VE in plain words: which guests no backup job covers, whose backups are overdue, which production VMs are stopped, what's going on with one VM. Start, shut down or reboot a guest and take snapshots from the same chat, with a confirmation step before anything changes. There is no tool that deletes a guest, restores a backup or rolls back a snapshot.
Built by Mojood Connect as a working demo for Proxmox. It runs against any Proxmox VE 8 or 9 through its REST API, with an API token. This repository includes a script that sets up a local Proxmox VE 9.2 (Proxmox's official arm64 build, in a VM on an Apple Silicon Mac) with SAMPLE guests for a made-up company, Harbor Trading, so you can try it without touching a real cluster.
Tools
Tool | What it does | Changes anything? |
| Nodes (CPU, memory, uptime), storage use, guests running and stopped, backup jobs | No |
| VMs and containers by name, id, tag or state, with CPU and memory in use | No |
| One guest: cores, disks, notes, snapshots, last backup, whether a backup job covers it, recent tasks (who did what) | No |
| Guests in no backup job, overdue backups, stopped production guests, old snapshots, storage filling up, guests short of memory | No |
| Start, shut down (cleanly) or reboot a VM or container | Yes, after confirmation |
| Take a snapshot, with a note saying who asked for it | Yes, after confirmation |
How changes are made safe. A call to power_guest or snapshot_guest without a confirmation changes nothing:
it returns a plain summary ("Start mail-relay (VM 104 on lima-pve, now stopped). It is tagged prod.") and a one-time
code. The change happens only when the same request comes back with that code, within 10 minutes. A code works once,
and only for the request it was issued for. The server's instructions tell the model to show the summary and wait
for the user's yes. Proxmox's own task log records every change under the token's user.
Least privilege. The demo's token belongs to its own Proxmox user, claude@pve, with a custom role holding only
VM.Audit, VM.PowerMgmt, VM.Snapshot, Datastore.Audit and Sys.Audit, plus VM.Backup and
Datastore.AllocateSpace (on the backup storage only), because Proxmox lists a guest's backups only to users who
could back it up. No tool makes, restores or deletes a backup.
Related MCP server: Proxmox MCP Server
Try it locally
Needs an Apple Silicon Mac (M3 or later, for nested virtualization) with Lima, uv and Python 3.13, about 6 GB of free memory and 40 GB of disk.
scripts/reset.sh # Proxmox VE 9.2 in a Lima VM (first run installs it), filled with SAMPLE guests
uv run --env-file .env proxmox-mcp # MCP server on http://127.0.0.1:8008/mcp (Streamable HTTP)scripts/up.sh installs Proxmox VE the way Proxmox's
Debian 13 guide describes, adds a ZFS pool
(on a file) so VMs and containers can be snapshotted, creates the claude@pve user and its token, and a read-only
viewer@pve user for the web UI at https://127.0.0.1:8006. Secrets go only into the git-ignored .env and are never
printed. The local certificate is self-signed, so .env sets PVE_VERIFY_TLS=0; keep it on for a real installation.
Claude Desktop: add this to claude_desktop_config.json (Settings › Developer), with the path to this folder:
{
"mcpServers": {
"proxmox": {
"command": "uv",
"args": ["run", "--directory", "/path/to/proxmox-mcp", "--env-file", "/path/to/proxmox-mcp/.env", "proxmox-mcp", "--stdio"]
}
}
}Then ask: "Which servers aren't backed up?", "What's going on with erp-app?", "Snapshot erp-app before tonight's update, and start mail-relay again."
Your own Proxmox VE: create a user and an API token with the rights above
(pveum user token add <user> <name> --privsep 0), then set PVE_URL, PVE_TOKEN_ID (user@realm!name),
PVE_TOKEN_SECRET and PVE_SAMPLE=0.
The SAMPLE guests
Six VMs (Alpine Linux, really booting) and four LXC containers for Harbor Trading: an ERP database and app server, a
file server, a mail relay that was left stopped, a retired CRM with a 96-day-old snapshot, a staging web server, two
web containers, monitoring and a VPN gateway. A nightly backup job covers most of them but not all, and one guest's
newest backup is 9.9 days old. Backups and snapshots are real; scripts/seed.sh moves a few of their timestamps back
to give the estate a history. Everything in it is made up.
Tests
uv run --env-file .env pytest # unit tests (a fake Proxmox API), plus live tests when the local Proxmox runsWhat a production version adds
This demo uses one API token. A production server for Proxmox customers would add sign-in with each person's own Proxmox account (their realm, LDAP or OpenID), so Claude sees and does exactly what their roles allow; clusters with several nodes; Proxmox Backup Server; hosting with an audit log of every tool call; and a directory listing. That is what Mojood Connect builds.
License
Apache 2.0. Proxmox is a registered trademark of Proxmox Server Solutions GmbH; this project is not made or endorsed by Proxmox Server Solutions GmbH.
Available Tools
6 toolsfind_guestsFind guestsCRead-onlyIdempotent
VMs and containers with status, tags, CPU and memory in use now, and uptime.
Inputs: tag, kind, query, status. Returns: total, guests
guest_detailsA guest in detailBRead-onlyIdempotent
One guest: status and use, cores and disks, notes, its snapshots, its last backup and whether a backup job covers it, and its recent tasks from Proxmox's task log (who did what, when).
Inputs: guest (required). Returns: cores, disks, guest, notes, +6 more
needs_attentionWhat needs attentionBRead-onlyIdempotent
Guests no backup job covers, overdue backups, production guests that are stopped, old snapshots, storage filling up, and guests short of memory.
Inputs: backup_days. Returns: memory_high, old_snapshots, backups_overdue, storage_filling, +2 more
overviewOverviewBRead-onlyIdempotent
Nodes (CPU, memory, uptime), storage use, how many guests run or are stopped, and the backup jobs.
Inputs: no named parameters. Returns: vms, nodes, running, stopped, +3 more
power_guestStart, shut down or reboot a guestADestructive
Start, cleanly shut down, or reboot a VM or container. The first call changes nothing and returns a summary and a confirmation code; it happens only on a second call with the code, after the user has said yes.
Inputs: guest (required), action (required), confirmation. Returns: done, guest, problem, summary, +2 more
snapshot_guestTake a snapshotA
Take a snapshot of a VM or container (it keeps running). The first call changes nothing and returns a summary and a confirmation code; the snapshot is taken only on a second call with the code, after the user has said yes.
Inputs: name (required), guest (required), description, confirmation. Returns: done, guest, problem, summary, +2 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool targets a distinct concern: health triage (needs_attention), cluster-wide status (overview), guest listing (find_guests), single-guest drill-down (guest_details), power actions, and snapshots. The only mild overlaps are needs_attention vs overview (both aggregate health) and find_guests vs guest_details (list vs detail), but the descriptions make the boundaries clear enough.
All names use snake_case, but the conventions are mixed: find_guests/power_guest/snapshot_guest are verb_noun, guest_details is noun_noun, and needs_attention/overview are bare noun phrases with no verb. It remains readable, but the pattern is not predictable across the set.
Six tools is a reasonable, well-scoped set for a Proxmox monitoring/ops surface, and each tool clearly earns its place. It is on the lean side for a broad hypervisor domain, but not thin enough to be a problem.
Read paths (overview, guest listing/detail, attention scan) and two guarded write actions (power, snapshot) are covered, but major lifecycle operations are missing: create/clone/delete guest, backup job creation/run/restore, and storage or migration actions. An agent asked to provision or remove a VM, or manage backups, would hit a dead end.
Maintenance
Related MCP Connectors
Manage VeriTeknik servers, DNS, backups and support tickets from your AI assistant.
Backups of servers, Docker and Zimbra to your own S3. Restore by chat; changes need 2FA approval.
Provides capabilities that let LLM agents perform a range of infrastructure management tasks.
Manage, check, investigate and automate server, database and storage backups from your AI assistant.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage Proxmox VE infrastructure, including VMs, containers, storage, and cluster operations via natural language.MIT
- AlicenseCqualityDmaintenanceEnables management of Proxmox VE environments, including VMs, containers, storage, and cluster operations through natural language.7653 npmMIT
- AlicenseAqualityBmaintenanceEnables natural language interaction with Proxmox VE clusters for managing VMs, containers, storage, and snapshots.2711 npm3MIT
- FlicenseBqualityDmaintenanceEnables natural language management of Proxmox VE VMs and containers, including lifecycle, snapshots, cloud-init, and secure multi-step automation workflows.65-