Proximo: Proxmox control for agents with an audit ledger
Proximo
An MCP server for Proxmox VE, Backup Server, Mail Gateway and Datacenter Manager: plan before action, a change ledger and undo
- 94 ★ on the repository
- Last commit
Broad access
Why this level
- The agent gets control of virtual machines and containers, including stop, migration and deletion
- Optional lanes run commands inside containers and on the node
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add mcp/proximoDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The agent gets control of virtual machines and containers, including stop, migration and deletion
- Optional lanes run commands inside containers and on the node
This is third-party code. Review the repository files before installing.
What it does
Proximo gives an agent control of Proxmox through six tools that cover every API address of four products: Proxmox VE, Proxmox Backup Server, Proxmox Mail Gateway and Proxmox Datacenter Manager. By the author's count that is 1,804 published addresses, of them 884 reads and 785 mutations. The server is read-only by default. Any change first returns a plan: a verdict, the current state of the target and the exact edit. Then a call with `confirm=true`, an armed access and a blast-radius tier are needed. Every action goes into a tamper-evident ledger that `audit_verify` checks. Where the platform offers the means, the previous record is captured before a change and undo goes back through the vendor's own write. There are optional lanes behind separate switches and command allowlists: running a command inside a container and on a node through ssh and `pct exec`. `uvx proximo-proxmox doctor` checks the token. It runs locally with no cloud and no telemetry.
Who it is for. Administrators of home labs and server rooms on Proxmox who want an agent to handle diagnostics and changes while keeping a record of every step.
Good fit when
- A container is slow and the agent must read node status, logs and guest state
- You want to see the plan for stopping or migrating a guest before it runs
- Before changing settings you want a snapshot and an undo
- You need to verify that the log of the agent's actions was not tampered with
Not a fit when
- You need Kubernetes or cloud VM orchestration: the server works only with the four Proxmox products
- You cannot create a token with limited rights: without one the safe mode loses its point
- You want edits without a plan or confirmation: every change goes through both steps
Example request
Why is container 105 thrashing? Read the node status and logs, and if a fix is needed show the plan and change nothing until I answer.MCP
- Transport
- stdio, http
- Authentication
- API key
Environment variables
PROXIMO_API_BASE_URLrequired- Proxmox API address, for example https://pve:8006/api2/json
PROXIMO_TOKEN_PATHrequired, secret- Path to a token file in the form USER@REALM!TOKENID=SECRET
Limitations
API access to Proxmox by token and Python to run through `uvx` are required, and the client must wait for startup of about 3.5 seconds: set a 60-second timeout or a client default may drop the server silently. Start with a read-only token: the server is useful even without write rights.
Undo exists where the platform offers a write primitive, but not for every change. Since version 0.51.0 the license is AGPL-3.0-or-later. The shell and command lanes stay off until the operator enables them and are judged like any change. Check the author's claims about protection against `VERIFY.md` in the repository.
How to disable. Remove the server with `claude mcp remove proximo` and revoke the token in Proxmox. The ledger and estate memory stay in files on your machine next to the ledger and are deleted by hand.
FAQ
How do I connect Proximo to Claude Code?
Run `claude mcp add proximo` with the variables `PROXIMO_API_BASE_URL` and `PROXIMO_TOKEN_PATH`, and the launch command `uvx proximo-proxmox`. The secret stays in a file and only the path goes into the client config.
Can the agent change something without my confirmation?
No. A change first returns a plan and runs only with `confirm=true`, an armed access and a blast-radius tier. Reads need no confirmation.
Which Proxmox products are supported?
Proxmox VE, Proxmox Backup Server, Proxmox Mail Gateway and Proxmox Datacenter Manager.
How do I undo a change?
With `proximo_call pve undo <id>`: the server writes the previous record back through the vendor's own write. Undo is not available for every change.
How do I get a least-privilege token?
`uvx proximo-proxmox mint pve` prints a runbook for the least-privilege token, and `doctor` shows what the token can do.
Discussion
No questions or reviews yet.
Related
MCP serversA Proxmox VE MCP server with 341 tools: virtual machines, containers, storage, cluster and backups, with a read-only mode.
MCP server for Proxmox VE: manage VMs, LXC, snapshots and backups from an agent with permission control and command approval
A PowerShell module and skill for Claude Code and Codex: the agent finds, starts and snapshots Proxmox VE VMs via the API.
A self-hosted homelab hub with a built-in MCP server: the agent gets 32 tools limited by per-key API scopes
A Go CLI that compares a server with its last snapshot, reports only changes that matter and serves them to an agent via MCP
The official Prometheus MCP server: PromQL queries, metrics, rules and alerts plus built-in runbooks for troubleshooting.
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| Proximo: Proxmox control for agents with an audit ledger (this card) | no | API key | 94 | |
| ProxmoxMCP-Plus | no | key is optional | 649 | an MCP for Proxmox without a tamper-evident ledger or a plan before changes |
| NetBox MCP Server | yes | API key | 255 | NetBox network inventory with no hypervisor control |
README in short
The README explains the idea of a trust layer in detail: plan, proof, undo and diagnosis are on by default, while consent and containment are chosen by the operator. It goes on to a quick start, a table of surfaces and tools, installation and running, a separate verification file `VERIFY.md` and version notes up to 0.52.0.