Proxmox MCP 控制助手

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). 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.48.1: on PyPI, GitHub, and GHCR (signed multi-arch image). New in 0.48.1 (pool tokens read their pool; what a clone needs). In PVE an ACL on a deeper path replaces what is inherited there, so mint pve --write --scope /pool/<name> left both tokens unable to read the pool; the recipe now also prints the grant of PVEAuditor on the pool to the user and the write token, audit privileges only (a token minted before needs those two lines run once). The write recipe and SETUP say what a clone of a template outside the scope needs: VM.Clone, Datastore.AllocateSpace and SDN.Use, measured from the vendor's own refusals. Recent: 0.48.0 made a restore without unique say, in its plan and its receipt, that it keeps the backup's identity. 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 construction: the door advertises six schemas and nothing else. Measured on this release, tools/list over 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.

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.

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. Forge a byte yourself and watch the chain refuse: <a href="VERIFY.md">VERIFY.md</a>, section 2.}</p>