proxmox-safe-mcp
# 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
```sh
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
```sh
uv sync --locked --extra test
uv run --locked pytest
uv run --locked python -m compileall -q src tests
uv build
```
See [architecture and operations](docs/ARCHITECTURE.md) and [security details](docs/SECURITY.md). MIT © 2026 Ben Gauger.
TDQS
Scored across 5 tools
Each tool targets a distinct aspect of the Proxmox environment: cluster status, node status, guest listing, guest power control, and guest snapshotting. There is no overlap in purposes, making selection unambiguous.
The names mix noun-initial patterns (cluster_status, node_status, guest_power) with verb-initial patterns (list_guests, snapshot_guest). This inconsistency is noticeable but still readable and predictable overall.
With only 5 tools, the server is tightly scoped and each tool serves a clear purpose. This is well-balanced for a specialized MCP server focused on monitoring and safe guest operations.
The set covers status, listing, power, and snapshot operations but lacks lifecycle management (create, update, delete guests). While potentially intentional for a 'safe' server, it leaves notable gaps for full Proxmox administration.