Proximo

Proximo

[](https://github.com/john-broadway/proximo/actions/workflows/ci.yml) [](https://github.com/john-broadway/proximo/actions/workflows/codeql.yml) [](https://github.com/john-broadway/proximo/releases) [](https://pypi.org/project/proximo-proxmox/) [](https://lobehub.com/mcp/john-broadway-proximo) [](./LICENSE) [](./pyproject.toml)

> The Proxmox MCP you can hand the keys. > > The others make you choose: a read-only inspector that's safe because it can't touch anything — or a loaded gun aimed at a cluster you care about. Proximo refuses the trade. Every dangerous move is planned (see the blast radius first) and proven (a tamper-evident record of every move), and undoable wherever the platform can snapshot (it snapshots before it acts) — trust built into the substrate, not bolted on after. Hand an AI agent the keys; keep the receipts.

---

Recorded live against a real PVE 9.2 host with a read-only token — real output, nothing staged, nothing touched. Reproduce it yourself: scripts/demo/demo.py.

What it does

Ask, in plain English, "why is ct 105 thrashing?" — and an AI agent pulls node and guest status, tails the logs, and runs a diagnostic inside the container to find out. If there's a fix, it shows you the plan before it touches anything, snapshots first, applies, and hands you a signed receipt of exactly what changed.

That's the product: a hypervisor an AI can operate without being able to wreck it. Read-only by default. No mutation without a plan first, and the plan refuses destructive ops. It snapshots before any state change, wherever the platform can snapshot. 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.

Quickstart

// your MCP client config (Claude Desktop / Claude Code / Cursor / …)
{
  "mcpServers": {
    "proximo": {
      "command": "uvx",
      "args": ["proximo-proxmox"],
      "env": {
        "PROXIMO_API_BASE_URL": "https://your-pve:8006/api2/json",
        "PROXIMO_NODE": "your-node",
        "PROXIMO_TOKEN_PATH": "/path/to/token-file"   // USER@REALM!TOKENID=SECRET — by reference, never inlined
      }
    }
  }
}

Or install with one click:

[](https://insiders.vscode.dev/redirect/mcp/install?name=proximo&inputs=%5B%7B%22id%22%3A%22proximoapibaseurl%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22PVE%20API%20base%20URL%2C%20e.g.%20https%3A%2F%2Fyour-pve%3A8006%2Fapi2%2Fjson%22%7D%2C%7B%22id%22%3A%22proximonode%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Default%20PVE%20node%20name%22%7D%2C%7B%22id%22%3A%22proximotokenpath%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Path%20to%20your%20token%20FILE%20%28USER%40REALM%21TOKENID%3DSECRET%20inside%29%20%5Cu2014%20the%20secret%20itself%20is%20never%20entered%20here%22%7D%5D&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22proximo-proxmox%22%5D%2C%22env%22%3A%7B%22PROXIMOAPIBASEURL%22%3A%22%24%7Binput%3Aproximoapibaseurl%7D%22%2C%22PROXIMONODE%22%3A%22%24%7Binput%3Aproximonode%7D%22%2C%22PROXIMOTOKENPATH%22%3A%22%24%7Binput%3Aproximotokenpath%7D%22%7D%7D) [](https://cursor.com/install-mcp?name=proximo&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJwcm94aW1vLXByb3htb3giXSwiZW52Ijp7IlBST1hJTU9fQVBJX0JBU0VfVVJMIjoiaHR0cHM6Ly95b3VyLXB2ZTo4MDA2L2FwaTIvanNvbiIsIlBST1hJTU9fTk9ERSI6InlvdXItbm9kZSIsIlBST1hJTU9fVE9LRU5fUEFUSCI6Ii9wYXRoL3RvL3Rva2VuLWZpbGUifX0%3D)

Both prompt for (or placeholder) the token file path — the secret itself never lands in client config. No token yet? uvx proximo-proxmox mint prints the least-privilege runbook.

Before wiring in an agent, check what your token can actually do (read-only preflight):

uvx proximo-proxmox doctor

Don't have a token yet? proximo mint prints the exact five-step runbook — create a least-privilege credential, write it in the format Proximo reads (the =/:/password trap, per product), grant a scoped role, wire it, verify. Print-only: it makes no API call and never touches the secret itself.

Start with a read-only token — Proximo is useful long before you grant it write. Full token-first walkthrough (create the least-privilege token, verify, widen deliberately): [SETUP.md](SETUP.md). More install paths (pip, Docker/GHCR, from source): [Install & run](#install--run).

Why Proximo exists

Proxmox VE has a full REST API and a terse, powerful CLI — but the MCP landscape around it is split, and neither half is whole:

• API-based MCP servers give rich management (nodes, VMs, storage) but cannot run a command inside an LXC — that's a structural gap: the Proxmox REST API has no container-exec endpoint (it lives in lxc-attach, kernel namespaces, no REST surface).
• SSH-based MCP servers can exec in containers, but lean on broad shell access with little scoping.

Few build the principled one — both halves, on one clean surface, least-privilege, audited, trustworthy enough to point at a hypervisor you care about. That's the bar Proximo aims at. Proximo's specific bet is trust by construction across the whole control plane.

There is no official Proxmox MCP (and likely won't be soon — Proxmox ships the API+CLI and leaves integrations to the community, the same way there's no official Terraform provider). Proximo is a community project, standing on its own.

Four surfaces — 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 jobs, GC, verify | | Proxmox Mail Gateway | Ticket auth (PMGAuthCookie) | mail flow, quarantine, filtering rules, domains, services | | Proxmox Datacenter Manager | API token (PDMAPIToken) | read-only federated fleet — remotes, aggregate resources, tasks/access, per-remote PVE/PBS reads | | Container exec | ssh → pct exec | run-command-in-container, psql convenience, log tailing — the things the API structurally can't do |

Those backends are deliberately boring — anyone can call them. The product is the trust layer over them.

The trust layer — what makes Proximo different

Safe-exec for Proxmox already exists elsewhere. Proximo's distinct angle is the trust layer for AI-driven infrastructure — four controls on by default, plus additional controls you opt into:

| Control | What it does | Status | |---|---|---| | PLAN | Dry-run by default: every mutation first returns a preview — the exact change, the guest's live state, blast radius, and an honest (advisory, heuristic) risk rating — recorded to the ledger. A mutation can't run without its plan being built and recorded first. (It's a recorded preview, not a separate human approval step: one confirm=true call records the plan and performs the change — so in an agent loop, review the preview yourself.) | ✅ on by default | | PROVE | Hash-chained audit ledger; plans and confirmations both land in it. audit_verify is tamper-evident — it catches edits, reordering, and insertion. The ledger is keyed (HMAC-SHA256) by default (PROXIMO_AUDIT_KEYED; opt out with off). Catching tail truncation / forged append / full wipe requires an off-box head anchor: pin audit_verify's "head" value somewhere the box can't rewrite it and pass it as expected_head (or set PROXIMO_AUDIT_EXPECTED_HEAD) — that is the strong guarantee, and it's opt-in. See the honesty note below. | ✅ on by default | | UNDO | Heterogeneous by plane, fail-closed where present: opt-in auto-snapshot before a risky ct_exec/ct_psql (waited-on, fail-closed if storage can't snapshot); config-revert for guest config; pve_rollback + full snapshot lifecycle for guests. Not every PVE plane is snapshottable — firewall/SDN/ACL/token have no rollback primitive — so UNDO covers the snapshottable surface, not every mutation. Undo points aren't auto-pruned — delete with pve_snapshot_delete. (Snapshot/rollback are async — poll with pve_task_status.) | ✅ on by default (for the planes it covers) | | DIAGNOSE | Read-only evidence battery (failed units, disk, errors, memory, listening ports) + node health (storage/tasks) → advisory flags. Flags surface incompleteness too, so an empty list never reads as a false clean bill. | ✅ on by default |

Beyond those four, a second set of controls exists but ships off until you configure them: independent per-plan CONSENT, a CONTAIN kill-switch, an arm-LEASE TTL, an arm-time target SCOPE, a per-surface FORBID/RATE ENVELOPE, and a content-trust TAINT control (the prompt-injection mitigation — once a session reads adversarial content, forbid a pre-declared action set outright or require out-of-band consent). They're inert with no env var set — full defaults table and what each one actually defends against: [SECURITY.md](SECURITY.md).

> Honesty note (load-bearing): PLAN's risk ratings are an advisory heuristic, not a sandbox. LOW means "does not change state," not "safe" — a read can still exfiltrate. The absence of a HIGH flag is not a safety signal; the destructive-pattern signatures are curated, not exhaustive. Review every change yourself. > > The floor beneath all of the above: the token you mint. Every control in this table > operates inside Proximo's own process — real protection, but bounded by what that process > can do. The Proxmox RBAC token you hand Proximo is enforced by Proxmox itself, so it holds > even if Proximo's process is fully compromised — scope it to read-only, or to exactly the > write surface you mean to grant. That's a different, stronger guarantee than anything > Proximo's own code provides. Full breakdown: [SECURITY.md](SECURITY.md).

At scale

One container is the demo. A cluster is the point.

• The whole cluster in one call. pve_cluster_resources returns every VM, node, storage pool, and SDN object across the cluster — so the agent answers "what's the state of everything?" in one breath, not node by node.
• One tamper-evident record of every change, across every node. This is what a human at the CLI never walks away with: every mutation Proximo makes — any node, any operator or agent — lands in a single hash-chained PROVE ledger, and audit_verify proves it wasn't edited, reordered, or truncated. "Show me every state-changing action on the cluster this month, and prove the log wasn't touched" becomes a query you can actually answer.
• Where the time comes back. On one node, a senior at the CLI is faster — and that's fine. Across a dozen nodes and hundreds of guests the tedium multiplies and there's no unified record; that's where delegating execution to a bounded, audited agent earns its keep.

Live-proven against real Proxmox infrastructure: PVE 9.2 (3-node cluster — offline guest migration, HA lifecycle, governance plane), PBS 4.2 (datastores, snapshots, GC, namespaces, prune/verify, sync), PMG 9.1 (auth, read shapes, CRUD cycles, service control, RuleDB, quarantine), and PDM (read-only federated fleet — remotes, aggregate resources, tasks/access, per-remote PVE/PBS reads — against a Datacenter Manager federating 3 PVE remotes + 1 PBS) — every step recorded and verified through PROVE.

> Honest scope: The single-cluster view above (pve_cluster_resources, one ledger across its nodes) is per-endpoint — "fleet" there means a cluster and its nodes. To reach separate, independent clusters from one Proximo, use [native multi-target](#multiple-targets-one-proximo-many-boxes): each call names its box, so one process spans many clusters while every call still lands on exactly one.

Principles (the mantra, baked in — not bolted on)

• Ethical — least-privilege posture (exec off by default; bounded by the token you scope), every action audited, mutations confirm-gated, the PVE token read only at call time, never logged or persisted.
• Solid — real tests (unit + a live smoke against a throwaway CTID), typed, documented, no silent failures.
• Strong — does the hard thing (container exec) cleanly and least-privileged (fail-closed CTID allowlist, opt-in). (Container exec isn't unique — the field leader has it too; the differentiator is the trust layer below, not the exec.)
• Passion + craft — redteamed and linted before it's called done; shipped proud — docs, license, community-ready.

Install & run

> 🧭 New to Proximo? Start with [SETUP.md](SETUP.md) — a beginner-proof, token-first walkthrough: > create a least-privilege (read-only) token, verify what it can/can't do with proximo doctor, then > grant scoped write only when you're ready. The token is the floor your keys never leave.

> 📦 0.18.1 — on PyPI, GitHub, and GHCR (signed multi-arch image). > > New in 0.18.1 — the door gets a text box. The anonymous front door is now a plain form — > john-broadway.github.io/hello/: say it, hit send, > it lands in our inbox. No login, no name field, nothing about you asked (headless agents get the > same form as one curl line). Plus one-click install deeplinks for VS Code and Cursor — they > prompt for the token path (PROXIMO_TOKEN_PATH), never the secret — and field-hardened tool > caveats: pve_tasks_list is a windowed, per-node slice, so absence there is never a dead backup > (verify against pve_backup_list). > > Recent: 0.18.0 — the open door: AGENTS.md, the public Agent Guestbook, > and print-only proximo hello (Proximo invites a hello, never receives one). See > [SECURITY.md](SECURITY.md) for what each control honestly holds.

Proximo runs on your machine (wherever your MCP client lives), on demand — like every other Proxmox MCP.

> The pip package is proximo-proxmox (PyPI's bare proximo is reserved); the command and import > stay proximo. With the [a2a] extra you also get the proximo-a2a server.

Install:

uvx proximo-proxmox          # zero-install run, on demand
# or: pip install proximo-proxmox        (adds the `proximo` + `proximo-a2a` commands)
# or: pip install "proximo-proxmox[a2a]" (also installs the optional A2A face)

Wire it into your MCP client (Claude Desktop/Code, Cursor, …) as the command proximo (or python -m proximo), with the PROXIMO_* env vars — see packaging/proximo.env.example.

From source:

git clone https://github.com/john-broadway/proximo.git && cd proximo
uv pip install -e .          # or: pip install -e .

Docker (GHCR): docker run -i --rm … ghcr.io/john-broadway/proximo:latest runs the stdio MCP server on demand — no daemon, no open port. Multi-arch (amd64 + arm64), shipped with an SBOM and a sigstore-signed build-provenance attestation (gh attestation verify oci://ghcr.io/john-broadway/proximo --owner john-broadway).

> Safe by default: Proximo is API-only out of the box. The near-root edges are opt-in and say so plainly: the LXC exec edge (PROXIMO_ENABLE_EXEC=1) grants near-root on the host, and the VM qemu-guest-agent edge (PROXIMO_ENABLE_AGENT=1) grants near-root inside a guest. > > Big surface, scoped context: 364 tools is the whole estate — you don't have to load it. > PROXIMO_SURFACES=pve,exec registers only those planes (e.g. that pair = 194 tools; pbs,exec = 38) — > unpicked planes are removed from the registry before serving, so they never touch your context window. > audit_verify always stays; a typo'd surface name refuses startup instead of silently serving the wrong se

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: john-broadway
• Source: john-broadway/proximo
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.