Proximo

What john-broadway/proximo MCP server does

The john-broadway/proximo MCP server gives MCP clients access to four Proxmox product surfaces: Proxmox Virtual Environment, Proxmox Backup Server, Proxmox Mail Gateway, and Proxmox Datacenter Manager. It also supports executing diagnostic commands inside containers through the same governed control plane.

The toolset is read-only by default. An agent can inspect node and guest status, examine logs, and investigate a container before making a change. When an operation would mutate state, the server produces a plan first rather than applying the mutation on the initial call. The plan names the expected blast radius. Changes produce a tamper-evident record in a hash-chained audit ledger.

How it works

The server runs locally as a Python package and communicates with a Proxmox API endpoint. MCP clients send requests through the server’s dispatch path, which applies the same trust controls across the supported transports. The README describes the design in terms of planning, proof, undo, and diagnosis; consent and containment are additional controls that can be raised by the operator.

Snapshot behavior depends on the platform operation. Proximo can snapshot before a risky in-container command and refuses to run that command when a required snapshot cannot be taken. For supported configuration changes, it retains the prior state so the change can be reversed. These safeguards depend on primitives available from the underlying Proxmox platform.

Setup and configuration

Install and run the package with uvx proximo-proxmox. Configure the MCP client with these environment variables:

• PROXIMO_API_BASE_URL: the Proxmox API base URL, such as an endpoint ending in /api2/json.
• PROXIMO_NODE: the default Proxmox VE node name.
• PROXIMO_TOKEN_PATH: a file containing the token reference in the form USER@REALM!TOKENID=SECRET.

The setup example supports Claude Desktop and Cursor. The token secret is kept in the referenced file rather than placed directly in the MCP client configuration. The repository also documents uvx proximo-proxmox doctor for a read-only preflight of what the configured token can do, and uvx proximo-proxmox mint for a least-privilege token runbook.

Tools and capabilities

The john-broadway/proximo MCP server covers:

• Proxmox VE resource and guest operations.
• Proxmox Backup Server operations.
• Proxmox Mail Gateway operations.
• Proxmox Datacenter Manager operations.
• In-container diagnostic execution.
• Mutation planning with named blast radius.
• Snapshot-before-operation behavior where supported.
• Hash-chained audit records for changes.

The README’s verification example queries the server’s tool registry directly, while the listing describes the release as providing 365 tools. The exact available tool set should therefore be checked against the installed version.

Limitations and notes

A Proxmox API endpoint, node name, and token file are required for the documented setup. Begin with a read-only token and grant write permissions only when needed. Snapshot and undo behavior is not universal: it depends on the platform exposing the necessary primitive. In particular, a risky in-container command is blocked when its required snapshot cannot be created.

The server is described as sovereign and agent-agnostic: the operator supplies the infrastructure and token, and the audit ledger is owned locally. The repository states that it does not phone home and does not require a standing cloud service unless the operator opts into one.