Provides a governed interface for Proxmox products that plans, records, and enables undoing of infrastructure changes.
Also known as john-broadway/proximo, proximo, proximo-proxmox
- Stars
- 94
- Tools
- 6
- Downloads, 30 days
- 3,133
- Latest version
- 0.52.0
- Last commit
- Nov 15, 2026
- License
- AGPL-3.0
What is Proximo MCP?
Proximo provides a governed interface for Proxmox products that plans, records, and enables undoing of infrastructure changes. It exposes 6 tools, such as proximo_find, proximo_plan, proximo_read.
Summary generated from the project's README
About Proximo MCP server
Proximo provides a governed interface for managing Proxmox infrastructure, specifically covering PVE, PBS, PMG, and PDM products. It is designed for developers and operators who want to grant AI agents access to their hypervisors without risking uncontrolled changes. The server operates locally via MCP clients like Claude Desktop, Cursor, or Claude Code, using a provided API base URL and a path to a token file for authentication.
What distinguishes this server is its built-in trust layer that focuses on planning and accountability. Instead of executing commands immediately, the system generates a plan detailing the target, the exact change, and the blast radius for review. It maintains a tamper-evident, hash-chained ledger of all actions and enables undoing mutations by capturing the state before a change is applied. This approach allows an AI to diagnose and operate infrastructure while ensuring every move is recorded and reversible where the platform allows.
What you can do with it
- 1Diagnose container performance issuesAn AI agent can investigate why a specific container is struggling by pulling status logs and running diagnostics.
- 2Revert recent infrastructure mutationsUsers can restore previous states using recorded receipts that capture the data before it was altered.
- 3Verify audit log integrityDevelopers can ensure that the history of infrastructure changes has not been tampered with or truncated.
Written from the project's README. Every use case is checked against a quote from it.
How to install Proximo MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Proximo MCP in Claude Code
$ claude mcp add proximo -- uvx proximo-proxmoxInstall Proximo MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"proximo": {
"command": "uvx",
"args": [
"proximo-proxmox"
]
}
}
}Install Proximo MCP in VS Code
.vscode/mcp.json
{
"servers": {
"proximo": {
"type": "stdio",
"command": "uvx",
"args": [
"proximo-proxmox"
]
}
}
}Install Proximo MCP in VS Code CLI
$ code --add-mcp '{"name":"proximo","type":"stdio","command":"uvx","args":["proximo-proxmox"]}'Install Proximo MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"proximo": {
"command": "uvx",
"args": [
"proximo-proxmox"
]
}
}
}Install Proximo MCP in Codex
$ codex mcp add proximo -- uvx proximo-proxmoxInstall Proximo MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.proximo] command = "uvx" args = ["proximo-proxmox"]
Install Proximo MCP in Gemini CLI
$ gemini mcp add -s user proximo uvx -- proximo-proxmoxInstall Proximo MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"proximo": {
"command": "uvx",
"args": [
"proximo-proxmox"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for proximo-proxmox 0.52.0 in an isolated container with no network and no keys. It answered and listed 6 tools.
Proximo MCP tools 6
Read from the server with tools/listproximo_findRead-onlyREAD-ONLY: find API addresses by plain words ('list datastores'). A verb picks the method. Returns access and blast-radius tier. 5 by default.
proximo_planRead-onlyREAD-ONLY, mutates nothing: the governed verdict (armed, tier, consent) for one address, with the parameters you gave and the required ones you lack; fields='name1,name2' or 'all' shows the vendor's full schema. A mutation's plan also reads the target: current, change, noop. Run before proximo_call. path may be words: one match is planned, several come back to pick from.
proximo_readRead-onlyREAD-ONLY: run a GET by /path, or by words with no slash. args = query parameters (params: old name). Rows come lean with a total; fields='all' or 'name,status' for others; over the cap you get counts and a next line. since='24h': what changed, from the door's snapshots. wait=N on .../tasks/{upid}/status waits up to N s (max 600). diagnose=true on a node or guest path: health and advisory flags. Credentials come back withheld.
proximo_callActionMUTATION: run a governed POST/PUT/DELETE. Without confirm=true it returns the plan (verdict, consent id, current, change) and mutates nothing. Refused unless the operator is armed AND the address has an authored blast-radius tier. Every call, refused or executed, is receipted. Task-backed calls are waited on (wait=N s, default 60, max 600; 0 submits only). method=undo with path=<undo.id> puts a receipt's capture back, plan first; withheld or unpublished keys come back as skipped.
audit_entriesRead-onlyREAD-ONLY: the PROVE ledger, newest first, bounded; says when it truncated.
audit_verifyRead-onlyREAD-ONLY: walk the chain, report the first break; expected_head catches a cut tail; path=<archive> checks a sealed archive.
| proximo_find | READ-ONLY: find API addresses by plain words ('list datastores'). A verb picks the method. Returns access and blast-radius tier. 5 by default. | Read-only |
| proximo_plan | READ-ONLY, mutates nothing: the governed verdict (armed, tier, consent) for one address, with the parameters you gave and the required ones you lack; fields='name1,name2' or 'all' shows the vendor's full schema. A mutation's plan also reads the target: current, change, noop. Run before proximo_call. path may be words: one match is planned, several come back to pick from. | Read-only |
| proximo_read | READ-ONLY: run a GET by /path, or by words with no slash. args = query parameters (params: old name). Rows come lean with a total; fields='all' or 'name,status' for others; over the cap you get counts and a next line. since='24h': what changed, from the door's snapshots. wait=N on .../tasks/{upid}/status waits up to N s (max 600). diagnose=true on a node or guest path: health and advisory flags. Credentials come back withheld. | Read-only |
| proximo_call | MUTATION: run a governed POST/PUT/DELETE. Without confirm=true it returns the plan (verdict, consent id, current, change) and mutates nothing. Refused unless the operator is armed AND the address has an authored blast-radius tier. Every call, refused or executed, is receipted. Task-backed calls are waited on (wait=N s, default 60, max 600; 0 submits only). method=undo with path=<undo.id> puts a receipt's capture back, plan first; withheld or unpublished keys come back as skipped. | Action |
| audit_entries | READ-ONLY: the PROVE ledger, newest first, bounded; says when it truncated. | Read-only |
| audit_verify | READ-ONLY: walk the chain, report the first break; expected_head catches a cut tail; path=<archive> checks a sealed archive. | Read-only |
Configuration
PROXIMO_API_BASE_URLPROXIMO_TOKEN_PATH
| Name | Description | |
|---|---|---|
| PROXIMO_API_BASE_URL | — | |
| PROXIMO_TOKEN_PATH | — |
Automated checks
Ran Nov 16, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablejohn-broadway/proximo is public and reachablegithub.com/john-broadway/proximo ↗Pass
- Package names this repository as its sourceproximo-proxmox names john-broadway/proximo as sourcepypi.org/project/proximo-proxmox/ ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for proximo-proxmoxpypi.org/project/proximo-proxmox/ ↗Pass
- Open source license (OSI)AGPL-3.0spdx.org/licenses/AGPL-3.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-15github.com/john-broadway/proximo ↗Pass
- OpenSSF ScorecardOpenSSF Scorecard 8.4 / 10; weakest: Code-Review 0, Fuzzing 0, Contributors 3scorecard.dev/viewer/?uri=github.com/john-broadway/proximo ↗Pass
- Package name not close to a popular packageNo popular package one edit away from proximo-proxmoxPass
- No critical advisory in the package or its dependencies32 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model6 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubNamed for Proximo, the lanista of Gladiator. The story is the design, joint for joint.
He armed his fighter with exactly what he needed, never more. He answered for every move in the arena. A lanista, not a jailer. The Spaniard earns his name by conduct, on the record, and the helmet comes off: truth said plainly, at cost. His last act opened the cages, holding the wooden sword of his own freedom. A tool should hope to end that well.
"Win the crowd and you will win your freedom."
The others make you pick: a read-only toy, or full keys and pray. Proximo won't. Every dangerous move is planned: the verdict, the live target and the change, before anything runs. Every move is proven: a tamper-evident record. And undoable wherever the platform gives us a primitive: a mutation captures the record it is about to change and puts it back through the vendor's own write; a risky in-container command can take a snapshot first, and refuses to run if it can't.
Trust built into the substrate, not bolted on after. Hand an AI agent the keys; keep the receipts.
Sovereign and agent-agnostic. Your metal, your token, a ledger you own. No cloud, no phone-home, no standing server unless you opt in.
What it does
Ask, in plain English: "why is ct 105 thrashing?" An AI agent pulls node and guest status, tails the logs, and (if you opened that lane) runs a diagnostic inside the container to find out.
If there's a fix, it shows you the plan before it touches anything: the verdict, the target as it stands, the exact change. Takes a snapshot first if you ask it to, and won't run if it can't. Applies. Hands you a keyed receipt of exactly what changed, with the before-state captured so it can be put back.
It does all of that with six tools, over every address the four Proxmox products publish. No wrappers, no catalog to page through, no tool per endpoint: find the address, plan it, read or call it, and prove the record. The whole surface fits a small local model's window.
That's the product: a hypervisor an AI can operate without being able to wreck it.
Read-only by default. No mutation runs on the first call: it returns its blast radius as a plan for you to see first. A tamper-evident receipt for every change.
The comparison isn't Proximo vs. the GUI. It's Proximo vs. handing an LLM your root token and hoping.
Don't take our word for any of it. Verify it yourself.
# 1. The tool count is real. Ask the door itself, cold (=> 6).
# (in a clone of this repo, after `uv sync`)
uv run python -c "import asyncio; from proximo.core.doors.mcp import build_server; \
print(len(asyncio.run(build_server().list_tools())))"
# 2. The container image is what the repo built. Sigstore provenance (exit 0 = verified):
gh attestation verify oci://ghcr.io/john-broadway/proximo:latest --owner john-broadway
# 3. The security posture is graded by a third party, not by us:
# https://scorecard.dev/viewer/?uri=github.com/john-broadway/proximo
The rest is in VERIFY.md: forge a ledger byte and watch verify() refuse, grep
the outbound surface for phone-home (there is none). These checks work on any tool, from any
vendor. Demand them everywhere.
Quickstart
// your MCP client config (Claude Desktop / Claude Code / Cursor / …)
{
"mcpServers": {
"proximo": {
"command": "uvx",
"args": ["proximo-proxmox"],
"timeout": 60, // startup is ~3.5s; a 3s client default drops the server silently
"env": {
"PROXIMO_API_BASE_URL": "https://your-pve:8006/api2/json",
"PROXIMO_TOKEN_PATH": "/path/to/token-file" // USER@REALM!TOKENID=SECRET, by reference, never inlined
}
}
}
}
Claude Code, one line:
claude mcp add proximo --env PROXIMO_API_BASE_URL=https://your-pve:8006/api2/json \
--env PROXIMO_TOKEN_PATH=/path/to/token-file -- uvx proximo-proxmox
Or install with one click:
Both prompt for the token file path; the secret never lands in client config. No token yet? uvx proximo-proxmox mint pve prints the least-privilege runbook.
Then preflight what your token can actually do (read-only):
uvx proximo-proxmox doctor
Start with a read-only token. Proximo is useful long before you grant it write. Full token-first walkthrough: docs/SETUP.md · more install paths: Install & run.
Why Proximo exists
Everything that touches a Proxmox product is a call: the web UI, pct and qm on a host, curl against the API, an agent's tool. Most of those calls leave no plan behind them, no receipt, and no way back. Proximo is the one client that governs the call before it runs, records it, and can put the record back, whichever door it came in by. Trust by construction:
| A call on its own | Through Proximo | |
|---|---|---|
| Before it runs | nothing | a plan, recorded first: the verdict, the live target, the exact change, the blast radius |
| Record of what happened | app logs, editable | keyed, hash-chained ledger; audit_verify catches edits, reordering and, against a pinned head, truncation |
| Undo | by hand, if you kept notes | the record captured first, restored through the vendor's own write |
| Command inside an LXC | broad SSH | opt-in, fail-closed allowlist, judged like any mutation |
| Products covered | one at a time | PVE + PBS + PMG + PDM, one governed plane |
| Verify the artifact you run | varies | signed image · PyPI provenance · SBOM · Scorecard |
Proximo is a community project, standing on its own. MCP, A2A, REST and a shell with no model in the loop are its doors; the governance is the product.
The trust layer: what makes Proximo different
The spine has six pillars. Four stand by default:
| Control | What it does |
|---|---|
| PLAN | Every mutation first returns a recorded preview: the exact change, live state, blast radius, an advisory risk rating. Nothing mutates without its plan recorded; one confirm=true call records and performs. |
| PROVE | Keyed (HMAC-SHA256), hash-chained audit ledger; audit_verify catches edits, reordering, insertion. Pin the head off-box (expected_head) to catch truncation too: that's the strong guarantee, and it's opt-in. |
| UNDO | One rule: every mutation with a GET twin captures the record before it runs, and the receipt carries an undo.id; the restore is the vendor's own write at the same path, with the captured record, as a governed mutation (planned, armed, receipted, itself undoable). A container command can take a snapshot first and then fail closed if it can't. Where the vendor publishes no write to put a record back (a delete, a collection, a path with no PUT) the answer is a sentence, never a guessed reverse call. |
| DIAGNOSE | Read-only evidence battery + node health → advisory flags that surface incompleteness too, so an empty list never reads as a false clean bill. |
Two are yours to raise, by design, off until their state paths exist, because both are only worth having if those paths sit outside the agent's reach. A pillar Proximo raised for you would be a pillar the agent could lower for itself:
| Pillar (off until configured) | What it holds |
|---|---|
| CONSENT | Independent, out-of-band approval per plan: an agent (compromised, confused, or steered by injected text) cannot confirm its own mutation. Grants live in a directory only you write (PROXIMO_CONSENT_DIR), expire on a TTL, and never clear a taint. |
| CONTAIN | The kill-switch: one trip file halts every mutation immediately, mid-incident, no redeploy and no restart. Checked fresh on every mutation; fails closed. Put the trip path where only you can write (PROXIMO_CONTAIN_TRIP_PATH). |
proximo doctor reports the spine: which pillars stand, which sockets are empty, and exactly how to fill them. Four more controls ship off until configured: ARM (a mutation runs only while the served token is the write token), a FORBID/RATE ENVELOPE, TAINT (the prompt-injection mitigation), and PRINCIPAL (who-asked attribution). Scope and lease are not Proximo's any more: the write token's own ACL is the scope and its own expire is the lease, both enforced by Proxmox, and proximo mint prints the commands that make such a token. What each control defends against: SECURITY.md.
Honesty note (load-bearing): risk ratings are an advisory heuristic, not a sandbox —
LOWmeans "no state change," not "safe," and the absence of aHIGHflag is not a safety signal. Review every change yourself. The floor beneath it all is the token you mint: Proxmox RBAC holds even if Proximo's process is fully compromised — a stronger guarantee than anything Proximo's own code provides. Scope it to exactly what you mean to grant: SECURITY.md.
Hold any tool to this, including this one: The Keys Test. Ten questions to ask before you hand an AI agent real infrastructure. Proximo's own scorecard published, partials included.
Demo
The record defends itself:
Surfaces & tools: one control plane
| Surface | Backend | For |
|---|---|---|
| Proxmox VE | REST API + scoped token | node/guest lifecycle, storage, SDN, identity, HA, firewall |
| Proxmox Backup Server | REST API + scoped token | datastores, namespaces, snapshots, sync, GC, verify, tape |
| Proxmox Mail Gateway | Ticket auth | mail flow, quarantine, filtering rules, domains, services |
| Proxmox Datacenter Manager | API token | federated fleet: reads plus governed control (power/snapshot/migrate, dry-run-first) |
| Container and node shell | ssh → pct exec, a fixed host battery |
run-command-in-container, psql, log tailing, a host health read: what the API structurally can't do. Opt-in lanes, each behind its own switch and allowlist, judged like any mutation |
Those backends are deliberately boring. Anyone can call them. The product is the trust layer over them.
Six tools, every address. The vendor publishes the API; Proximo serves it whole and governs each address by what it is: 1,804 published addresses across the four products, 884 reads, 785 mutations open to an armed operator each with an authored blast-radius tier, 32 opened by an operator's switch (guest agent, container and node shell), 5 on the download lane, 20 held on purpose with a sentence, 78 excluded as not JSON calls. The record is generated from the vendor's own schema and a stale copy fails the suite: docs/arena.md.
Where an operator actually starts, in the six-tool grammar:
| You want to… | Say | Worth knowing |
|---|---|---|
| Find the address | proximo_find "list datastores" |
verbs pick the method; the vendor's own words match |
| See the whole cluster at once | proximo_read pve /cluster/resources |
lean rows (names, states, ids) and a total; fields=all for the vendor's rows |
| Find out why a container is sick | proximo_read pve /nodes/{node}/lxc/{vmid} diagnose=true |
the battery: status, storage, failed tasks, and the shell probes if that lane is open |
| Power / lifecycle, any mutation | proximo_plan, then proximo_call … confirm=true |
the plan reads the target first; nothing moves without confirm=true, an arm and a tier |
| Put it back | proximo_call pve undo <undo.id> |
the captured record, written back through the vendor's own PUT |
| Preflight a token / config | proximo doctor |
run this before wiring an agent |
| Prove the record wasn't touched | audit_verify |
on every door, always |
The six tools with typed inputs: docs/TOOLS.md · the walkthrough: docs/SETUP.md.
Install & run
The core alone, no model in the loop: the same install ships proximo-core pve GET /nodes/pve1/status (or --plan on any address: the verdict and the published schema, touching nothing), and the estate memory behind proximo-core learn | where 105 | uses local | changed 24h: what the governed reads have seen, answered from one file beside the ledger, no model, no network. Its import closure is httpx and nothing else (measured by a test); every published address on all four products; the same arm gate, tiers and audit ledger as the MCP door. The core has its own network doors, each the 0.44 face's perimeter with the core behind it: proximo-mcp-http (MCP over streamable HTTP), proximo-http (REST, POST /tools/{name} with an OpenAPI document) and proximo-a2a (an Agent2Agent card whose skills are the six tools).
📦
0.52.0: on PyPI, GitHub, and GHCR (signed multi-arch image).New in 0.52.0 (the ticket is the arm; the vendor's door answers on every product). A person arms by logging in:
proximo-core armprompts in a terminal of their own and serves the vendor's ticket, dead on its own at the vendor's two hours; a job with nobody at a keyboard keeps its token pair. A plan now says what the vendor's own permission check would answer the served credential on PVE, PBS and PDM, read from the vendor's rule and the vendor's own account of what the credential holds with nothing inferred between them: may, never with the missing privilege named, unknown, or in words (PMG names the roles its rule wants). The vendor's digest is the write lock: a plan carries the record's digest into the write, so a record that moved since the plan is the vendor's own 400. Proved in the lab under exactly the credentialsproximo mintinstalls. SECURITY.md says what a ticket is: the user's whole ACL, and a user may mint its own tokens.Recent: 0.51.0 moved the license to AGPL-3.0-or-later and kept a read under its cap; 0.50.1 let the operator raise the exit ceiling (
PROXIMO_EXIT_MAX_BYTES, up to 64 KiB, from alexdelprete's measurements on #114). See SECURITY.md for what each control honestly holds.
Proximo runs on your machine, on demand. No daemon, no open port.
uvx proximo-proxmox # zero-install run (PyPI package: proximo-proxmox; command stays `proximo`)
# or: pip install proximo-proxmox the core, MCP door included
# or: pip install "proximo-proxmox[a2a]" + the optional A2A face
# or: pip install "proximo-proxmox[http]" + the optional HTTP/OpenAPI face
# or: pip install "proximo-proxmox[mcp-http]" + the optional MCP-over-streamable-HTTP face
# or, from source: git clone https://github.com/john-broadway/proximo.git && cd proximo && uv pip install -e .
Wire it into your MCP client as the command proximo, with the PROXIMO_* env vars; see packaging/proximo.env.example.
Docker (GHCR): docker run -i --rm … ghcr.io/john-broadway/proximo:latest. Multi-arch, SBOM, sigstore-signed provenance (gh attestation verify oci://ghcr.io/john-broadway/proximo --owner john-broadway). Mirrored to Docker Hub (docker.io/jebroadway/proximo, identical digest); GHCR stays the signed primary.
Safe by default: API-only out of the box. The two near-root edges are opt-in and say so loudly: LXC exec (
PROXIMO_ENABLE_EXEC=1, near-root on the host) and the qemu-guest-agent edge (PROXIMO_ENABLE_AGENT=1, near-root in a guest). Each is scoped by its own fail-closed allowlist.Smallest footprint by construction: the door advertises six schemas and nothing else. Measured on this release,
tools/listover stdio is 5,544 bytes on the wire (about 1,400 tokens at the four-bytes-a-token heuristic; 1,568 as a stock 1.5B's chat template renders it, counted by its server), and that is the whole cost of connecting; the estate behind it is searched, not loaded. There is nothing to scope: a plane you have not configured is simply not reachable, a plane you have is reachable whole, and the gates do not shrink with the doorway. PLAN and PROVE apply to every address however small the model.
The network faces (experimental, opt-in): proximo-a2a speaks Agent2Agent. proximo-http serves plain HTTP + generated /openapi.json for no-code clients. proximo-mcp-http serves MCP itself over Streamable HTTP (the SDK's native transport) for networked MCP clients: no third-party stdio→HTTP bridge, so the perimeter stays Proximo's. LXC on your Proxmox host, one line: on the PVE node as root, bash -c "$(curl -fsSL https://raw.githubusercontent.com/john-broadway/proximo/main/packaging/lxc/ct/proximo.sh)" builds a Debian 13 container running proximo-mcp-http with Proximo from PyPI, its own service user, and a minted bearer on port 41243. Community-scripts engine (MIT) pointed at Proximo's own tree, their telemetry off; the same line inside the container updates it. Details: docs/SETUP.md, files: packaging/lxc/.
All three serve the full surface through the same spine as MCP. No second code path; trust spine and token scope inherited. Fail-closed perimeter: loopback, bearer-token required off-localhost, DNS-rebind and CSRF defended. Details: SECURITY.md.
Proximo MCP questions
How do I add Proximo MCP to Claude Code?
Run claude mcp add proximo -- uvx proximo-proxmox in your terminal. Add --scope user to make it available in every project.
How do I add Proximo MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Proximo MCP provide?
It exposes 6 tools, including proximo_find, proximo_plan, proximo_read, proximo_call, audit_entries.
How does Proximo handle dangerous mutations?
Every dangerous move is planned with a verdict, target, and change preview before execution, and it provides a tamper-evident record.
Can I undo changes made through Proximo?
Yes, Proximo captures the state before a mutation and provides an undo ID to restore it through the vendor's own write mechanism.
Is Proximo cloud-based?
No, it is sovereign and agent-agnostic, running on your own metal with no phone-home capability.