Proxmox Read-only MCP
Provides read-only inspection of Proxmox infrastructure, including node status, guest inventory and configuration, storage, backup jobs, backup task history, snapshots, and firewall rules through a scoped HTTPS adapter or fictional mock backend.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Proxmox Read-only MCP show me the status of all nodes and VMs"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Proxmox Read-only MCP
A Python MCP server for inspecting infrastructure through a small, read-only tool surface. Start with fictional infrastructure, then explicitly opt into a scoped HTTPS adapter for your own Proxmox environment.
This reference exposes infrastructure inventory and status without granting modification privileges or returning every upstream field. It is available under the MIT license.
What works
Eight tools expose node status, guest inventory/configuration, storage, backup jobs, backup task history, snapshots and firewall rules. The official MCP SDK handles actual stdio initialization, discovery and execution. Input validation, fixed GET routes, explicit guest scope and field projection constrain access. Upstream token privileges independently enforce read-only permissions.
Backend | Data | Credentials | Evidence |
| Fictional in-memory fixtures | None | Actual local MCP client/server tests |
| User-configured Proxmox HTTPS API | Private token file | Injected-transport tests, no real-cluster verification |
Related MCP server: proxmox-mcp
Install and try
Requires Python 3.11 or newer; Python 3.13 is the tested SDK environment. From the repository root:
python3 -m venv .venv
.venv/bin/python -m pip install --require-hashes -r requirements.lock
.venv/bin/python -m pip install --no-index --no-deps --no-build-isolation -e .
.venv/bin/python examples/mcp_client.pyThe client launches a stdio server, initializes MCP, lists tools and calls fictional
infrastructure. No Proxmox connection or account is required. A dependency-free
domain example remains available as python3 examples/demo.py.
For a host that supports stdio MCP, launch the installed command:
.venv/bin/proxmox-readonly-mcp --backend mockIt waits for MCP messages on stdin, not interactive shell commands. Protocol output uses stdout. There is no network MCP listener. See host setup and generic configuration. No host settings are modified.
Your own Proxmox environment
Live mode requires an explicit backend selection, HTTPS origin, one node, allowed guest IDs and an owner-only token file. Custom CA bundles are supported with mandatory verification. Startup settings cannot be changed by tool arguments.
Follow live setup for token format, permissions and
limitations. .env.example documents settings; it is not loaded automatically.
No real endpoint or credential is supplied. Do not commit live settings or output.
Architecture and security decisions
The diagram shows the local host, MCP server, validated registry and separate mock/HTTPS adapters.
Stdio process access is the trust boundary; no remote user authentication is claimed.
Tools cannot choose a URL, node, role, HTTP method or arbitrary path.
The live adapter rejects redirects, ignores proxy environment settings, verifies TLS and bounds response size and body-read time. Upstream ACLs remain necessary.
Inventory lists return at most 200 items. The
truncatedfield indicates when the server omitted available rows to honor a result limit.The live adapter rejects responses with invalid identifier text in projected fields such as guest, storage and snapshot names.
Field filtering is not privacy redaction: real strings can still disclose details.
Backup jobs and task metadata do not prove that a backup can restore.
Tests, limits and evidence
PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src .venv/bin/python -m unittest discover -s tests -vTests exercise domain restrictions, fake HTTPS responses and real local MCP stdio sessions. No test contacts a live cluster. See claims, readiness and security review for results and gaps.
Live API schemas, token ACLs and certificate deployment require testing in the target environment. Response limits intentionally reject oversized payloads. No complete cluster inventory, rate limiting, modifications, remediation or restore operation is provided.
Planned improvements include versioned compatibility fixtures, stricter semantic response schemas and disposable-cluster integration tests. Read SECURITY.md and dependency notices.
Available Tools
8 toolsbackup_historyARead-onlyIdempotent
Read recent backup task metadata; this does not verify restore success.
Inputs: limit.
backup_jobsCRead-onlyIdempotent
Read selected backup scheduling metadata.
Inputs: no named parameters.
firewallARead-onlyIdempotent
Inspect selected firewall rules; no rule changes are available.
Inputs: no named parameters.
guest_configCRead-onlyIdempotent
Read selected resource configuration of one scoped guest.
Inputs: guest_id (required).
guest_snapshotsBRead-onlyIdempotent
Read snapshot metadata for one scoped guest.
Inputs: guest_id (required).
list_guestsARead-onlyIdempotent
List configured-scope virtual machines and containers.
Inputs: no named parameters.
node_statusARead-onlyIdempotent
Read status of the configured node; no infrastructure modifications.
Inputs: no named parameters.
storage_statusCRead-onlyIdempotent
Read selected storage availability and usage fields.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool targets a clearly distinct Proxmox resource or metadata category: node, guests, guest configuration, storage, backup schedules, backup history, snapshots, and firewall rules. The closest pair, backup_jobs and backup_history, is still clearly separated as scheduling metadata versus recent task metadata.
The set is consistently snake_case and mostly uses noun-based resource labels such as node_status, storage_status, backup_jobs, and guest_snapshots. The main deviation is list_guests, which uses a verb-first pattern while the rest are noun phrases.
Eight tools is well-scoped for a read-only Proxmox inspection server, covering the main resource areas without excessive surface area. Each tool corresponds to a meaningful read-only concern.
The server covers node, guest, storage, backup, snapshot, and firewall reads, but notable Proxmox read operations are absent, such as guest runtime status, task logs/details, network configuration, and cluster-level status. These gaps are workable for limited inspection but will cause dead ends for common read-only diagnostics.
Maintenance
Related MCP Connectors
Read-only MCP access to a documented IT fleet: state, changes, posture. 15 tools.
Infrastructure context for any AI: VMware, Nutanix, Kubernetes and cloud. Read-only, off production.
Read-only server insight: why a Linux server or K8s cluster is slow, failing or changed.
Inspect Exoscale: instances, volumes, SKS, DNS, IPs, quotas and usage; start, stop, reboot VMs.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables read-only interaction with Proxmox homelab VMs and containers, allowing LLM agents to list VMs, monitor status and performance metrics, view snapshots, and check cluster health through natural language queries.8MIT
- AlicenseNot gradedqualityCmaintenanceA PROXMOX implementation containing 152 tools covering QEMU VMs, LXC, unified guest power, storage admin, cluster/tasks, snapshots, backups (incl. scheduled jobs), migration, HA, firewall (incl. IPSet CIDRs), access control, replication, SDN (read), ACME (read), pools, and console tickets.46 PyPI1MIT
- FlicenseNot gradedqualityBmaintenanceEnables read-only interaction with Proxmox Datacenter Manager, allowing users to list and inspect remotes, VMs, containers, nodes, and storages through MCP tools.6-
- AlicenseNot gradedqualityCmaintenanceEnables read-only interaction with Proxmox VE API, providing tools to query nodes, guests, storage, firewall, backups, and recent tasks.5MIT