Skip to main content
Glama

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

mock (default)

Fictional in-memory fixtures

None

Actual local MCP client/server tests

live (opt-in)

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.py

The 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 mock

It 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 truncated field 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 -v

Tests 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 tools
backup_historyA
Read-onlyIdempotent

Read recent backup task metadata; this does not verify restore success.

Inputs: limit.

backup_jobsC
Read-onlyIdempotent

Read selected backup scheduling metadata.

Inputs: no named parameters.

firewallA
Read-onlyIdempotent

Inspect selected firewall rules; no rule changes are available.

Inputs: no named parameters.

guest_configC
Read-onlyIdempotent

Read selected resource configuration of one scoped guest.

Inputs: guest_id (required).

guest_snapshotsB
Read-onlyIdempotent

Read snapshot metadata for one scoped guest.

Inputs: guest_id (required).

list_guestsA
Read-onlyIdempotent

List configured-scope virtual machines and containers.

Inputs: no named parameters.

node_statusA
Read-onlyIdempotent

Read status of the configured node; no infrastructure modifications.

Inputs: no named parameters.

storage_statusC
Read-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

    A3.5/5.0

    Scored across 8 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness3/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables 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.
      8
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      A 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 PyPI
      1
      MIT