# Proximo > The Proxmox MCP you can hand the keys — VE + Backup Server + Mail Gateway + Datacenter Manager on one audited trust core (plan · prove · undo · diagnose). MCP + A2A. - **Type:** MCP server - **Install:** `agentstack add mcp-john-broadway-proximo` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [john-broadway](https://agentstack.voostack.com/s/john-broadway) - **Installs:** 0 - **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure) - **Latest version:** 0.1.0 - **License:** Apache-2.0 - **Upstream author:** [john-broadway](https://github.com/john-broadway) - **Source:** https://github.com/john-broadway/proximo ## Install ```sh agentstack add mcp-john-broadway-proximo ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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 ```jsonc // 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%22proximo_api_base_url%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%22proximo_node%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Default%20PVE%20node%20name%22%7D%2C%7B%22id%22%3A%22proximo_token_path%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%22PROXIMO_API_BASE_URL%22%3A%22%24%7Binput%3Aproximo_api_base_url%7D%22%2C%22PROXIMO_NODE%22%3A%22%24%7Binput%3Aproximo_node%7D%22%2C%22PROXIMO_TOKEN_PATH%22%3A%22%24%7Binput%3Aproximo_token_path%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](https://pypi.org/project/proximo-proxmox/), [GitHub](https://github.com/john-broadway/proximo/releases/tag/v0.18.1), and [GHCR](https://github.com/john-broadway/proximo/pkgs/container/proximo) (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/](https://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](https://github.com/john-broadway/proximo/discussions/20), > 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](https://github.com/john-broadway) - **Source:** [john-broadway/proximo](https://github.com/john-broadway/proximo) - **License:** Apache-2.0 Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-john-broadway-proximo - Seller: https://agentstack.voostack.com/s/john-broadway - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.