Proxmox MCP 控制助手

Install & run

📦 0.40.0: on PyPI, GitHub, and GHCR (signed multi-arch image). New in 0.40.0 (doctor says where near-root exec lands). ct_exec and the node shell ride an ssh target or run on the box itself, never the API, so the machine the API reads and the machine a near-root command lands on can differ, and nothing said so. proximo doctor now reports where exec lands, resolves the ssh target through ssh's own config, counts every name and address this machine goes by as one host, and flags a split target with a remedy you can follow as written. The shadow-key flag also compares every set-valued key the way its gate reads it, so a reordered allowlist is no longer a change, and the TLS warning counts a pinned fingerprint as verification. Recent: 0.39.1 made every allowlist refusal name the store that fed it. 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 MCP core

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 design: you don't have to load the whole estate: what a box serves is autoscoped to what it configures. A PBS-only box gets that plane's tools plus the always-on audit trail; PROXIMO_SURFACES=pve,exec scopes the searchable catalog to that pair (318 tools); a typo'd surface refuses startup rather than serving a surprise. Surfaces choose which planes are searchable, never how many schemas load; the doorway stays the default unless you name another with PROXIMO_TOOLSETS. Scoping is context hygiene, not an authorization control: it changes what is advertised, never what a token is allowed to do. The default doorway (dynamic mode) keeps four search-and-call tools resident (proximo_read runs read-only tools with an enforced readOnlyHint; proximo_call runs anything) plus the two ledger tools (audit_verify proves the chain, audit_entries reads who did what) and proximo_recall while estate memory is on (the default; PROXIMO_MEMORY=0 opts out), with the full catalog reachable by name. That narrowing is guarded at every entry point (0.27.0 closed a path where an opt-in flag could silently cut the registry to 5 tools), and the gates don't shrink with the doorway: PLAN and PROVE apply however small the visible surface gets.

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.

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.

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_NODE": "your-node",
        "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_NODE=your-node --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 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.

Demo

The record defends itself:

<p align="center"> <img src="https://raw.githubusercontent.com/john-broadway/proximo/main/docs/demo/hand-the-keys.svg" alt="Hand-the-keys demo: three agent moves land in the keyed hash-chained ledger and audit_verify answers ok=True keyed=True; an in-place edit breaks the chain at the exact line (ok=False); a truncation that fools the forward walk is caught by the pinned head" width="860"> </p>

<p align="center">_{Three agent moves land in the keyed ledger; one entry gets edited in place; <code>audit_verify()</code> breaks at the exact line, <b>ok=False</b>; the truncation a forward walk would miss is caught against the pinned head. Real code, real crypto, nothing staged, recorded on 0.30.0. Run it yourself anywhere: <a href="./scripts/demo/hand_the_keys.py"><code>scripts/demo/hand_the_keys.py</code></a> (needs only the pip package) · against your own host: <code>--live</code> · verify by hand: <a href="VERIFY.md">VERIFY.md</a>.}</p>