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

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:

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.