proxmox-mcp
Allows interacting with a Proxmox VE node/cluster, providing tools for listing nodes and guests, power management (start/stop/shutdown/reboot), reconfiguring CPU and memory, managing snapshots (list, create, rollback, delete), and performing one-shot backups (vzdump).
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-mcp list all guests with their CPU and memory usage"
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-mcp
A small MCP server that exposes a Proxmox VE
node/cluster as tools any MCP client (Claude Code, Claude Desktop) can call —
so instead of hand-writing curl against the Proxmox REST API, the assistant
calls clean tools like list_guests or start_guest.
Scope: read, power control, limited reconfigure (CPU/memory), plus snapshots and one-shot backups. It can inspect everything, start/stop/shutdown/reboot guests, adjust a guest's cores/memory, and manage restore points and vzdump backups. It does not create or delete the guests themselves.
Tools
Tool | Effect |
| Nodes with status, CPU, memory (GB), uptime |
| All VMs ( |
| Detailed status of one guest |
| Full provisioning config: cores, memory (MB), disks/mounts, network |
| Live interfaces + IP addresses (LXC direct; QEMU needs guest agent) |
| Storage pools with real usage (GB, %) |
| What's on a storage pool: templates, ISOs, backups, disk images |
| Recent task log for a node |
| One task's status, exit status, and log tail (by UPID) |
| Start a stopped guest |
| Graceful shutdown (preferred) |
| Hard stop (pulls the cord) |
| Graceful reboot |
| Reconfigure CPU cores and/or memory |
| A guest's snapshots |
| Take a snapshot |
| Irreversible — roll back to a snapshot (typed-confirm) |
| Delete a snapshot |
| Backup archives on a storage (newest first) |
| Back up a guest now (vzdump) |
type is "qemu" (VM) or "lxc" (container). Use list_guests to find
vmid/node/type.
Related MCP server: proxmox-mcp
Example
Ask your assistant "which guests use the most memory, and is anything
stopped?" — it calls list_guests() and gets clean, ready-to-reason data:
[
{"vmid": 100, "name": "web", "node": "pve1", "type": "lxc", "status": "running", "cpu_pct": 0.4, "mem_used_gb": 0.21, "mem_max_gb": 1.0, "uptime_hours": 412.6},
{"vmid": 101, "name": "db", "node": "pve1", "type": "qemu", "status": "running", "cpu_pct": 3.1, "mem_used_gb": 6.84, "mem_max_gb": 8.0, "uptime_hours": 412.6},
{"vmid": 102, "name": "backups", "node": "pve2", "type": "lxc", "status": "stopped", "cpu_pct": 0.0, "mem_used_gb": 0.0, "mem_max_gb": 2.0, "uptime_hours": 0.0}
]From there it can start_guest("pve2", 102, "lxc") or set_guest_resources(...)
— each a single-purpose, confirmable action, not a freeform shell command.
Setup
Linux / macOS
git clone https://github.com/nrohozen/proxmox-mcp
cd proxmox-mcp
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
cp .env.example .env # then edit .env with your real valuesWindows (PowerShell)
git clone https://github.com/nrohozen/proxmox-mcp
cd proxmox-mcp
py -3.12 -m venv .venv
.venv\Scripts\python -m pip install -r requirements.txt
copy .env.example .env # then edit .env with your real valuesPrefer a package install?
pip install .exposes aproxmox-mcpconsole command; set thePROXMOX_*vars in the environment or a.envin the working directory.
Configuration (.env)
Config lives in a .env file next to server.py (gitignored). server.py
loads it automatically, so the MCP client config just launches the server — no
env block required. Copy .env.example to .env and set:
Var | Example | Notes |
|
| scheme + host (+ optional |
|
| API token id (see Security) |
|
| API token secret |
|
| set |
Proxmox's API is on
:8006with a self-signed certificate by default, soPROXMOX_VERIFY_TLS=falseis typical on a LAN. For stricter TLS, front the API with a reverse proxy holding a trusted cert and pointPROXMOX_BASE_URLthere.A variable set explicitly in the client's
envblock still overrides.env.
Register with Claude Code (CLI)
With config in .env, registration just points at the server — no -e flags.
Use absolute paths to the venv's Python and server.py.
Linux / macOS
claude mcp add proxmox -s user -- \
/path/to/proxmox-mcp/.venv/bin/python \
/path/to/proxmox-mcp/server.pyWindows (PowerShell)
claude mcp add proxmox -s user `
-- C:\path\to\proxmox-mcp\.venv\Scripts\python.exe `
C:\path\to\proxmox-mcp\server.py-s user makes it available in every project. Verify with claude mcp list.
Tools load in a new Claude Code session.
Register with Claude Desktop
Copy claude_desktop_config.example.json to
%APPDATA%\Claude\claude_desktop_config.json (it only points at server.py;
config comes from .env), then fully restart Claude Desktop. The Proxmox tools
appear under the 🔌 / tools menu.
Security
Use a dedicated, least-privilege token — never root@pam. This server needs
read, power, CPU/memory reconfigure, and snapshot/backup privileges. Create a
scoped token once, on a Proxmox node:
# a role with exactly the privileges this server uses
pveum role add ProxmoxMCP --privs "VM.Audit,VM.PowerMgmt,VM.Config.CPU,VM.Config.Memory,VM.Snapshot,VM.Snapshot.Rollback,VM.Backup,Sys.Audit,Datastore.Audit,Datastore.AllocateSpace"
# a dedicated, non-root user + API token
pveum user add mcp@pve
pveum aclmod / -user mcp@pve -role ProxmoxMCP
pveum user token add mcp@pve proxmox --privsep 0
# -> copy the printed token id (mcp@pve!proxmox) and value into .envA token scoped this way can power-manage, resize, snapshot, and back up guests
but cannot open a host shell, change node/network/firewall config, or create
users/tokens — so a leaked token can't own the hypervisor. (Datastore.AllocateSpace
is needed only for writing backups; drop it to make the token read-plus-power only.)
The token secret lives in
.envin plaintext (gitignored) — keep it private..env.example(no secret) is the committed template.MCP clients prompt before running a tool; that confirmation is the human guardrail on the power-control tools.
Available Tools
20 toolscreate_backupA
Back up a guest now (vzdump) to storage. mode="snapshot" runs with no downtime.
mode:snapshot(live, default) |suspend|stop.compress:zstd(default) |gzip|lzo|0(none).
Returns the task UPID (track with task_status). Needs node, vmid, storage.
Inputs: node (required), vmid (required), storage (required), mode, +1 more.
create_snapshotA
Take a snapshot named name — the safety net before a risky change.
Optional description. Returns the task UPID (track with task_status).
Needs node, vmid, type.
Inputs: name (required), node (required), type (required), vmid (required), +1 more.
delete_snapshotA
Delete snapshot name (frees its disk usage; does not affect the running guest).
Needs node, vmid, type. Returns the task UPID.
Inputs: name (required), node (required), type (required), vmid (required).
guest_configA
Full provisioning config of a VM/container: cores, memory (MB), disks/mounts, network, etc.
Needs node, vmid, type ("qemu"/"lxc"). Returns Proxmox's raw config keys
(e.g. cores, memory, rootfs/mp0…, net0, ostype). Use this to see
how a guest is provisioned before calling set_guest_resources.
Inputs: node (required), type (required), vmid (required).
guest_networkA
Live network interfaces and IP addresses of a running guest.
LXC reads directly; QEMU requires the guest agent (returns a note if it's not installed/running). Needs node, vmid, type.
Inputs: node (required), type (required), vmid (required).
guest_statusB
Detailed current status of one VM or container.
Needs node (e.g. "pve1"), vmid, and type ("qemu" or "lxc"). Use list_guests first to find these.
Inputs: node (required), type (required), vmid (required).
list_backupsA
List backup archives on a storage, newest first. Optionally filter to one vmid.
Needs the node and storage id (from storage).
Inputs: node (required), storage (required), vmid. Returns: result
list_guestsA
List all VMs and containers across the cluster.
Returns vmid, name, node, type (qemu=VM, lxc=container), status, and usage. Optionally filter by type ("qemu" or "lxc").
Inputs: type. Returns: result
list_nodesA
List Proxmox nodes with status and resource usage (CPU, memory in GB, uptime).
Inputs: no named parameters. Returns: result
list_snapshotsC
List a guest's snapshots (plus the synthetic current state). Needs node, vmid, type.
Inputs: node (required), type (required), vmid (required). Returns: result
reboot_guestC
Reboot a guest gracefully. Needs node, vmid, type.
Inputs: node (required), type (required), vmid (required).
recent_tasksB
Recent task log for a node (migrations, starts, backups, etc.).
Inputs: node (required), limit. Returns: result
rollback_snapshotA
Roll a guest BACK to snapshot name — discards ALL changes since it. IRREVERSIBLE.
Two-step by design: call without confirm to get a preview (nothing
changes); then re-call with confirm set to the guest's exact name to
actually roll back. Needs node, vmid, type.
Inputs: name (required), node (required), type (required), vmid (required), +1 more.
set_guest_resourcesA
Change a guest's CPU cores and/or memory. RECONFIGURES the guest.
cores: CPU core count (LXC = total cores; QEMU = cores per socket).memory_mb: RAM in MB.
Provide at least one. For LXC this applies live (no reboot). For QEMU, core/
memory changes generally take effect on the next reboot. Read the current
values first with guest_config. Needs node, vmid, type.
Inputs: node (required), type (required), vmid (required), cores, +1 more.
shutdown_guestA
Gracefully shut down a guest (sends ACPI/clean shutdown to the OS).
Preferred over stop_guest. Needs node, vmid, type.
Inputs: node (required), type (required), vmid (required).
start_guestA
Start a stopped VM or container. Needs node, vmid, type ("qemu"/"lxc").
Inputs: node (required), type (required), vmid (required).
stop_guestA
Hard-stop a guest (pulls the virtual power cord — may lose unsaved data).
Use shutdown_guest unless the guest is unresponsive. Needs node, vmid, type.
Inputs: node (required), type (required), vmid (required).
storageA
List storage pools with real usage (GB). Optionally scope to one node.
Uses the per-node endpoint (which reports used/total/avail); with no node it queries every node so usage is populated rather than null.
Inputs: node. Returns: result
storage_contentA
List what's stored on a storage pool — templates, ISOs, backups, disk images.
content optionally filters by type: vztmpl | iso | backup | images
| rootdir. Useful for finding a template/ISO volid or seeing which disk
images live on a pool. Needs the node and the storage id (from storage).
Inputs: node (required), storage (required), content. Returns: result
task_statusA
Status (and tail of the log) of a Proxmox task by its UPID.
Get a UPID from recent_tasks or from a power tool's return value. Tells you
whether the task is running or finished, its exit status ("OK" or an error),
and the last log_lines lines of output.
Inputs: node (required), upid (required), log_lines.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Each tool targets a distinct operation: backup, snapshot lifecycle, guest configuration reading and modification, status queries, resource listing, power management, and task tracking. No two tools overlap in purpose.
All tool names follow a consistent verb_noun pattern using snake_case (e.g., create_backup, list_guests, rollback_snapshot). No mixing of styles or vague verbs.
With 20 tools, the server covers a broad range of Proxmox administration tasks. While it's slightly on the larger side, each tool serves a clear purpose and the count is still manageable for the domain.
The tool set lacks essential lifecycle operations: there is no tool to create or delete a guest, clone, or migrate. While backup, snapshot, and power control are covered, these missing functions create dead ends for common workflows.
Maintenance
Related MCP Connectors
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
The MCP server for Azure DevOps, bringing the power of Azure DevOps directly to your agents.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceAn open-source MCP server for managing Proxmox environments, including nodes, virtual machines, and containers. It enables users to perform inventory checks, status monitoring, and control operations directly through MCP-compatible tools.109 npm2MIT
- AlicenseBqualityDmaintenanceAn MCP server for Proxmox VE that enables read-only cluster inspection, VM/container lifecycle operations, snapshots, migration, and provisioning with safe confirmation gates.28MIT
- AlicenseCqualityCmaintenanceA comprehensive MCP server providing 92 tools for managing Proxmox Virtual Environment, including QEMU VMs and LXC containers.92190 npm6MIT
- AlicenseAqualityDmaintenanceMCP server for managing Proxmox VE resources, VM/CT lifecycle, snapshots, backups, and clones via natural language.23MIT