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.