Proxmox MCP 控制助手

Install & run

🧭 New to Proximo? Start with 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.20.0 — on PyPI, GitHub, and GHCR (signed multi-arch image). New in 0.20.0 — the receipts release. Every safety claim is now paired with a command that proves it. New VERIFY.md: forge a byte of the audit ledger and watch verify() refuse, grep the whole outbound surface to see there's no phone-home, verify the image's sigstore provenance — checks you run against the artifacts, not our word. Plus THREAT_MODEL.md, a CycloneDX SBOM on the wheel, an OpenSSF Scorecard badge, and a trust-core mutation smoke (4/4 tamper-detection mutants killed). No tool-count change (still 365) — this makes the existing guarantees checkable. The field is filling with "AI on Proxmox, but safe"; the answer is to raise the floor, not shrink anyone: whatever you run, make it prove itself. Recent: 0.19.1 — a self-audit release: a multi-agent pass over v0.19.0 found and fixed 23 real issues (headline: restore/prune from PBS work again), no tool-count change.

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:**

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). The same image is mirrored to Docker Hub (docker pull docker.io/jebroadway/proximo, identical digest) for those who prefer it; GHCR stays the signed primary.

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: 365 tools is the whole estate — you don't have to load it. PROXIMO_SURFACES=pve,exec registers only those planes (e.g. that pair = 195 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 set. The default path never touches the hypervisor host — management goes over the Proxmox API (scoped token). The two opt-in edges are the exceptions: exec uses your existing ssh to PVE to run pct exec as root on the host; the qemu-agent edge runs in-guest ops via the API. Both are off by default, each scoped by its own fail-closed allowlist (PROXIMO_CT_ALLOWLIST / PROXIMO_AGENT_ALLOWLIST), and say so loudly. (A Debian package is optional — the MCP world installs via uvx/pip/Docker, not apt. Status: debian/ now produces a working, installable .deb (dpkg-buildpackage -us -uc -b), lintian-clean with a man page and an autopkgtest smoke — but it is distributed nowhere; build-your-own from debian/. See debian/README.Debian.)

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:

_{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. More install paths (pip, Docker/GHCR, from source): Install & run.