pve-mcp

An MCP server for managing Proxmox VE (single node or cluster): query resources, manage VM/CT lifecycle, snapshots, backups, clones — from Claude Code or any MCP host.

• Works with both QEMU VMs and LXC containers, on single nodes and clusters.

• Tools that target one guest only need the vmid — the node and guest type are resolved automatically.

• Safety first: an optional read-only mode, confirm=true required for destructive operations, and guest command execution disabled by default.

Requirements

• Python >= 3.11 (a pinned 3.12 is used via uv)

• A Proxmox VE 7/8 host with an API token (see below)

Related MCP server: mcp-server-proxmox

Installation

git clone <this-repo> pve-mcp
cd pve-mcp
uv sync            # installs runtime + dev dependencies into .venv
uv run pytest      # optional: run the test suite

Or run it directly with uvx (no install):

uvx --from /path/to/pve-mcp pve-mcp

The console entry point is pve-mcp (stdio transport).

Creating a PVE API token

Authentication uses API tokens only (Authorization: PVEAPIToken=<id>=<secret>), never username/password tickets. Create a dedicated user and token on the PVE host (as root):

# 1. Dedicated user
pveum user add mcp@pve --comment "MCP server"

# 2a. Read-only usage: PVEAuditor on the whole tree
pveum acl modify / --users mcp@pve --roles PVEAuditor

# 2b. Management usage: PVEVMAdmin (VM/CT lifecycle, snapshots, backups)
pveum acl modify / --users mcp@pve --roles PVEVMAdmin
# For backup/restore you may also need PVEDatastoreUser on the backup storage:
pveum acl modify /storage/<backup-storage> --users mcp@pve --roles PVEDatastoreUser

# 3. Token
pveum user token add mcp@pve mcp --privsep 1

Note the privsep setting: with --privsep 1 (recommended) the token has its own ACLs — grant the roles above to the token too (pveum acl modify / --tokens 'mcp@pve!mcp' --roles PVEVMAdmin), or the token ends up with no permissions. With --privsep 0 the token inherits all permissions of the user.

The command prints the token secret once — store it safely.

Configuration (environment variables)

A .env file in the working directory is loaded automatically; see .env.example.

Registering with Claude Code

claude mcp add pve -e PVE_HOST=https://192.168.1.10:8006 \
  -e PVE_TOKEN_ID='root@pam!mcp' -e PVE_TOKEN_SECRET=xxx \
  -e PVE_VERIFY_SSL=false -- uvx --from /path/to/pve-mcp pve-mcp

Add -e PVE_MCP_READ_ONLY=true for a safe, audit-only setup.

Tools

Read-only (12, always registered)

Write (11, skipped when PVE_MCP_READ_ONLY=true)

Exec (1, requires PVE_MCP_ENABLE_EXEC=true)

Security model

1. Read-only mode — with PVE_MCP_READ_ONLY=true the write tools are not registered at all (they don't exist for the model), leaving exactly the 12 read-only tools.

2. Tool annotations — read-only tools carry readOnlyHint, the four destructive tools carry destructiveHint, so MCP hosts (e.g. Claude Code) can prompt appropriately.

3. confirm parameter — destructive tools refuse to run without confirm=true and explain the consequences first. Nothing is sent to PVE until confirmed.

4. Exec opt-in — pve_vm_exec (arbitrary command execution in guests) is only registered with PVE_MCP_ENABLE_EXEC=true, and never in read-only mode.

Combine with a least-privilege token: PVEAuditor for read-only setups, PVEVMAdmin for management.

Behavior notes

• Async tasks: write operations wait up to PVE_MCP_TASK_WAIT seconds for the PVE task to finish. Long operations (backups, clones, migrations) return {"status": "running", "upid": ...} — follow up with pve_task_status.

• Output: responses are JSON with a per-tool field whitelist; byte values keep the raw number and gain a *_human companion (e.g. "31.25 GiB").

• Errors: HTTP/auth/SSL errors are translated into actionable messages (e.g. 403 suggests the missing role; unknown vmids list the existing ones).

Development

uv sync
uv run pytest        # unit tests (PVE API mocked with respx)

See DESIGN.md for the full specification.