Skip to main content
Glama
proxmox-mcp

proxmox-mcp

by nrohozen

proxmox-mcp

tests License: MIT Python 3.10+

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

list_nodes()

Nodes with status, CPU, memory (GB), uptime

list_guests(type?)

All VMs (qemu) and containers (lxc): vmid, name, node, status, usage

guest_status(node, vmid, type)

Detailed status of one guest

guest_config(node, vmid, type)

Full provisioning config: cores, memory (MB), disks/mounts, network

guest_network(node, vmid, type)

Live interfaces + IP addresses (LXC direct; QEMU needs guest agent)

storage(node?)

Storage pools with real usage (GB, %)

storage_content(node, storage, content?)

What's on a storage pool: templates, ISOs, backups, disk images

recent_tasks(node, limit?)

Recent task log for a node

task_status(node, upid, log_lines?)

One task's status, exit status, and log tail (by UPID)

start_guest(node, vmid, type)

Start a stopped guest

shutdown_guest(node, vmid, type)

Graceful shutdown (preferred)

stop_guest(node, vmid, type)

Hard stop (pulls the cord)

reboot_guest(node, vmid, type)

Graceful reboot

set_guest_resources(node, vmid, type, cores?, memory_mb?)

Reconfigure CPU cores and/or memory

list_snapshots(node, vmid, type)

A guest's snapshots

create_snapshot(node, vmid, type, name, description?)

Take a snapshot

rollback_snapshot(node, vmid, type, name, confirm?)

Irreversible — roll back to a snapshot (typed-confirm)

delete_snapshot(node, vmid, type, name)

Delete a snapshot

list_backups(node, storage, vmid?)

Backup archives on a storage (newest first)

create_backup(node, vmid, storage, mode?, compress?)

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 values

Windows (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 values

Prefer a package install? pip install . exposes a proxmox-mcp console command; set the PROXMOX_* vars in the environment or a .env in 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

PROXMOX_BASE_URL

https://proxmox.example.com:8006

scheme + host (+ optional :port)

PROXMOX_TOKEN_ID

mcp@pve!proxmox

API token id (see Security)

PROXMOX_TOKEN_SECRET

xxxxxxxx-...

API token secret

PROXMOX_VERIFY_TLS

false

set false for a node's self-signed cert

Proxmox's API is on :8006 with a self-signed certificate by default, so PROXMOX_VERIFY_TLS=false is typical on a LAN. For stricter TLS, front the API with a reverse proxy holding a trusted cert and point PROXMOX_BASE_URL there.

A variable set explicitly in the client's env block 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.py

Windows (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 .env

A 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 .env in 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 tools
create_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

    B3.4/5.0

    Scored across 20 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness2/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      An 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 npm
      2
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      An MCP server for Proxmox VE that enables read-only cluster inspection, VM/container lifecycle operations, snapshots, migration, and provisioning with safe confirmation gates.
      28
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      MCP server for managing Proxmox VE resources, VM/CT lifecycle, snapshots, backups, and clones via natural language.
      23
      MIT