Proxmox Safe MCP

A focused Proxmox MCP server exposing bounded inventory/status reads and only two narrow mutation classes: allowlisted guest power actions and snapshot creation. Extracted from spectrenet-mcp commit 2e63f009d8f4642e17398685baef0251811d6637; this repository is self-contained.

Alpha: tests are synthetic. Proxmox API compatibility has not been certified against every release; test on non-production infrastructure.

Safety contract

• Nodes are explicitly allowlisted for node-targeted operations (node_status) and both mutation tools; guest types are only qemu and lxc; VMIDs must be positive integers.

• cluster_status and list_guests intentionally return cluster-wide API views and are not filtered by the node allowlist. Scope the dedicated Proxmox API account/token to limit what these read tools can see.

• Power actions are only start, shutdown, reboot, and stop.

• Snapshot names are 1–64 ASCII letters, digits, _, or -.

• Every mutation needs byte-for-byte APPROVE <action> <target> confirmation.

• Mutation responses are submission receipts, not completion proof. Verify the returned UPID and final state separately.

• There are no guest/snapshot deletion, host-power, storage mutation, allocation, migration, or configuration tools. node_status deliberately excludes storage enumeration.

• Responses/lists/audit fields are bounded and TLS verification defaults on.

Install and run

uv sync --extra test
uv run proxmox-safe-mcp --help
uv run proxmox-safe-mcp

The server uses MCP stdio. It does not load .env; use .env.example only as fake documentation and inject secrets through a supervisor or secret manager.

Verify

uv sync --locked --extra test
uv run --locked pytest
uv run --locked python -m compileall -q src tests
uv build

See architecture and operations and security details. MIT © 2026 Ben Gauger.