ProxmoxMCP-Plus: MCP and OpenAPI control for Proxmox VE

The gap ProxmoxMCP-Plus fills between agents and Proxmox VE

Proxmox VE has an HTTP API, and that API is not shaped for language models. An agent that wants to snapshot a container, wait for the task to finish, and then roll back has to discover endpoints, poll UPIDs, and handle token auth itself. The README describes the problem in exactly those terms: operators otherwise "stitch together raw API calls, one-off shell scripts, and custom job polling for every workflow." ProxmoxMCP-Plus is the layer that absorbs that work.

The intended audience is narrow and identifiable. This is for people running Proxmox VE who already use an MCP client such as Claude Desktop, Cursor, VS Code, Open WebUI or Codex, and who want those clients to touch real infrastructure. The project also targets HTTP automation through an OpenAPI bridge, which covers dashboards, internal tools and no-code workflows. Homelab operators are the obvious fit; the topics list includes homelab alongside qemu, lxc and automation. Anyone without a Proxmox VE host has nothing to connect it to.

One control plane, two access paths, and how jobs are tracked

The architecture is a server process that speaks two protocols over the same operational surface. The README states it exposes that surface as MCP for agent clients and as OpenAPI for HTTP automation. Internally the dependencies in pyproject.toml show the shape: mcp for the protocol layer, proxmoxer for talking to the Proxmox API, fastapi and uvicorn for the HTTP side, paramiko for SSH-backed container command execution, and mcpo, which is the bridge that turns an MCP server into OpenAPI.

Long-running operations get their own handling. The README says the project issues stable job_id values, tracks Proxmox UPID values, and supports polling, retry, cancel and audit history. That matters because most Proxmox operations are asynchronous: a backup or a snapshot rollback returns a task identifier, not a result. By persisting job state, the server lets a client ask about a job later instead of holding a connection open. Job state lives in a local SQLite file by default, and the README shows a jobs section with a sqlite_path key for storing it elsewhere.

Tool exposure is configurable, which is a deliberate design choice rather than an afterthought. The README explains that filtering is disabled by default so existing configurations keep exposing every tool, and that you configure exactly one mode under mcp: tool_allowlist or tool_denylist. The same filtering can be set through MCP_TOOL_ALLOWLIST or MCP_TOOL_DENYLIST. Two details in the README are worth quoting because they are the parts that bite: "An empty allowlist exposes no tools; an empty denylist hides none," and unknown names fail startup so a typo cannot silently widen access. Requiring exact lowercase tool names and refusing to start on a typo is a stricter posture than most MCP servers take, and it is the right call here, because a silently ignored allowlist entry would expose operations the operator thought they had hidden.

Installing ProxmoxMCP-Plus and running a first real query

Start with credentials and config, not with the server. The README instructs you to create a Proxmox API token with only the permissions your workflows need, then copy the example config:

cp proxmox-config/config.example.json proxmox-config/config.json

Edit proxmox-config/config.json. The README lists the minimum keys as proxmox.host, proxmox.port, auth.user, auth.token_name and auth.token_value. Add an ssh section if you want container command execution, and a jobs section if you want job state somewhere other than the default local SQLite file. If you plan to run live end-to-end checks, the README says to create a separate proxmox-config/config.live.json from proxmox-config/config.live.example.json rather than pointing live tests at a placeholder config.

For a local MCP client such as Claude Desktop or Cursor, the stdio path needs no container. The README gives this command, which runs the published package directly:

uvx proxmox-mcp-plus

The README says to verify success by having the client list get_nodes, get_vms and the job tools. If you prefer a normal install, pip install proxmox-mcp-plus followed by proxmox-mcp-plus does the same thing.

For a remote MCP client that supports Streamable HTTP, the Docker path exposes port 8000. The README's example generates a key, sets the mode and transport, mounts the config read-only, and points clients at http://<docker-host>:8000/mcp:

export MCP_API_KEY="$(openssl rand -hex 32)"
docker run --rm -p 8000:8000 \
  -e PROXMOX_MCP_MODE=mcp-http \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PORT=8000 \
  -e MCP_TRANSPORT=STREAMABLE_HTTP \
  -e MCP_API_KEY="$MCP_API_KEY" \
  -v "$(pwd)/proxmox-config/config.json:/app/proxmox-config/config.json:ro" \
  ghcr.io/rekklesna/proxmoxmcp-plus:latest

Every MCP HTTP request must carry Authorization: Bearer <MCP_API_KEY>. The README notes that MCP_API_KEY is separate from the OpenAPI-only PROXMOX_API_KEY so the two surfaces rotate independently. It also states plainly that if MCP_API_KEY is unset, Streamable HTTP remains unauthenticated for backward compatibility and logs a security warning at startup. Treat that warning as a failure, not a notice.

The OpenAPI path is the simplest to confirm, because it has a health endpoint. The compose file builds the API service on port 8811 and requires PROXMOX_API_KEY to be set before startup; the README gives this check:

docker compose up -d
curl -f http://localhost:8811/livez

A 200 from /livez means the bridge is up. It says nothing about whether your Proxmox token works, so the first meaningful test is a read-only call such as listing nodes.

Where the safety model stops and the operator has to start

The README enumerates the controls: Proxmox API tokens, OpenAPI bearer auth, command policy, approval tokens, TLS validation, and MCP HTTP Host and Origin controls. For reverse proxy deployments it shows MCP_DNS_REBINDING_PROTECTION=true with MCP_ALLOWED_HOSTS and MCP_ALLOWED_ORIGINS. Read that list carefully, because several entries are configuration you must supply rather than defaults that protect you.

The clearest example is authentication on the MCP HTTP path. The README states that an unset MCP_API_KEY leaves Streamable HTTP unauthenticated for backward compatibility. Backward compatibility is a defensible reason to ship that behaviour, but it means a container started without the variable is an open control plane for Proxmox. The startup warning is the only signal.

The second limitation is scope. ProxmoxMCP-Plus does not invent permissions. Whatever your Proxmox API token can do, the server can do, and the tool allowlist only narrows which tools are advertised to the client. A token with broad privileges paired with a permissive allowlist gives an agent the same reach as the token. The README's own advice, to create a token "with only the permissions your workflows need," is the actual boundary. The tool filter is a second layer, not the first.

The third is maturity. pyproject.toml classifies the project as Development Status 3 - Alpha. The README documents a broad surface: VM and LXC lifecycle, snapshot create, rollback and delete, backup and restore, ISO download and cleanup, node, storage and cluster inspection, SSH-backed container commands, and job tracking. An alpha classifier over that range means you should expect the API surface to move. The README does not document rollback of a failed restore, and it does not describe what happens to in-flight job records when the SQLite file is replaced or the schema changes between versions. If your workflow depends on restoring a backup and recovering cleanly when that restore fails, the documentation is silent on the recovery path.

How ProxmoxMCP-Plus differs from a plain Proxmox MCP server

The obvious alternative is a single-protocol MCP server for Proxmox: one process, stdio only, tools that wrap the Proxmox API directly. That design is simpler to reason about and has fewer moving parts. The difference in approach is what happens to asynchronous work. A plain wrapper typically returns the Proxmox task handle and leaves polling to the caller, so the agent has to loop, or the human does. ProxmoxMCP-Plus instead persists job records, assigns stable job_id values, and tracks UPIDs, which is what allows an agent to start a backup and check on it in a later turn.

The second difference is the OpenAPI bridge. A stdio-only server is invisible to anything that is not an MCP client. ProxmoxMCP-Plus runs the same operations behind a FastAPI service on port 8811, which is what makes dashboards, scripts and no-code tools viable against the same control plane. If you only ever use Claude Desktop on your laptop, that second surface is dead weight, and a smaller single-protocol server would serve you just as well with less to configure.

Licence, maintenance and the cost of keeping up

The project is MIT licensed, stated in both the LICENSE file and the pyproject.toml license field. MIT is permissive: you can use, modify and redistribute it, including in commercial settings, provided the copyright notice and licence text are preserved. That is a description of the licence terms, not legal advice; if you redistribute it inside a product, have your own counsel read the LICENSE file.

The maintenance signal is concrete. The last push to the repository was on 2026-09-04, and the most recent release, v0.5.15, carries the same date, following v0.5.14 on 2026-08-11 and v0.5.13 on 2026-08-10. The repository is not archived. Release cadence over those three versions is roughly one month apart with a same-day pair in August, and the version numbers are in the 0.5.x range, which is consistent with the alpha classifier.

Upgrade cost is where the pinned dependencies matter. pyproject.toml constrains mcp to >=1.8.0,<2.0.0, proxmoxer to >=2.0.1,<3.0.0, pydantic to >=2.0.0,<3.0.0, paramiko to >=5.0.0,<6.0.0, and requests to >=2.31.0,<3.0.0. Those upper bounds protect you from breaking major versions, but they also mean a future mcp 2.0 will require a coordinated upgrade of this project rather than a transitive bump. Python 3.11 or newer is required. The practical cost of tracking releases is low as long as you pin the package version yourself and read the release notes before moving, because a change to the tool allowlist semantics or the job schema is the kind of thing that would surface as a runtime failure rather than an import error.

Editorial conclusion

Adopt ProxmoxMCP-Plus if you already run Proxmox VE and want an MCP-capable agent or an HTTP client to perform VM, LXC, snapshot and backup operations through one audited surface. Do not adopt it if you need a stable API contract: pyproject.toml still classifies the project as Development Status 3 - Alpha, and the README does not document rollback of a failed restore. Before trusting it, verify two things on your own cluster: that your Proxmox API token is scoped to only the operations you intend to expose, and that MCP_API_KEY is set, since an unset key leaves Streamable HTTP unauthenticated for backward compatibility.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. RekklesNA/ProxmoxMCP-Plus on GitHub
5. Releases