ProxmoxMCP-Plus: an MCP and OpenAPI control plane for Proxmox VE
Use MCP and OpenAPI to safely control Proxmox VE VMs, LXCs, backups, and snapshots from LLMs and AI agents.
At a glance
- What is it?
- ProxmoxMCP-Plus wraps Proxmox VE operations in two interfaces, MCP for AI agents and OpenAPI for HTTP clients, so VM, LXC, snapshot and backup actions do not need hand-written shell scripts. It is a homelab-scale tool with a real safety model, and the safety model is also where its sharpest constraints live.
- Who is it for?
- Adopt ProxmoxMCP-Plus if you run Proxmox VE at homelab or small-cluster scale and want an AI client or an HTTP script to drive day-2 operations without writing a Proxmox API wrapper yourself. Do not adopt it if you need offline operation, if you cannot expose the Proxmox API token to the process running the server, or if you expect the tool list to be stable across upgrades.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 4 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap ProxmoxMCP-Plus fills between an LLM and Proxmox VE
Proxmox VE has a complete REST API, but an AI agent cannot call it usefully without a translation layer. The agent needs a tool schema it can reason about, a stable identifier for work that outlives a single request, and a boundary that stops a hallucinated call from deleting the wrong container. ProxmoxMCP-Plus is that layer. The README describes it as sitting "between AI clients and Proxmox VE so operators do not have to stitch together raw API calls, one-off shell scripts, and custom job polling for every workflow." That sentence is the whole pitch, and it is an accurate description of the work it removes.
The target user is the homelab operator who already runs Proxmox and wants an agent to handle routine tasks: start a VM, take a snapshot before an upgrade, roll it back when the upgrade breaks, check storage pressure across nodes. It is not aimed at a platform team managing hundreds of hypervisors, and nothing in the material suggests it claims to be. The scope is day-2 operations on hardware you own and can afford to have an agent touch.
Two access paths over one operation set
The project exposes the same operational surface twice. MCP covers Claude Desktop, Cursor, VS Code, Open WebUI, Codex and other MCP-capable agents. OpenAPI covers HTTP automation, dashboards, internal tools and no-code workflows. The operations listed in the README are VM and LXC lifecycle actions, snapshot create, rollback and delete, backup and restore, ISO download and cleanup, node, storage and cluster inspection, SSH-backed container command execution, and persistent job tracking.
Running two interfaces over one backend is a design decision with a cost. The README notes that MCP_API_KEY is "deliberately separate from the OpenAPI-only PROXMOX_API_KEY, so the two surfaces can be rotated independently." That is a sensible separation, but it also means two credential paths to configure and two places where a misconfiguration exposes the same Proxmox token. The benefit is that an agent-facing endpoint and a script-facing endpoint can be firewalled differently, which matters if the MCP side is reachable from a chat client and the OpenAPI side is not.
Job tracking is the part that makes async work usable
Most Proxmox operations are asynchronous. A backup or a clone returns immediately and finishes minutes later. The README states that the project provides "stable job_ids, Proxmox UPID tracking, polling, retry, cancel, and audit history" for long-running operations. This is the mechanism that lets an agent start a backup, return control to the user, and later answer a question about whether it finished. Without a stable job identifier, an agent has no way to correlate a Proxmox UPID with the request that produced it, and the conversation has to end with the operation in an unknown state.
Job state persists to SQLite by default. The configuration example shows a jobs section with a sqlite_path key, and the README says to add a jobs section "if you want job state persisted somewhere other than the default local SQLite file." Nothing in the supplied material describes a supported database backend other than SQLite, so treat the default file as the persistence layer and plan for it to live on storage that survives container restarts. If the SQLite file sits inside an ephemeral container filesystem, job history disappears on every redeploy and the audit trail is gone.
Getting it running: config file, then one of three runtimes
Setup starts with credentials. Create a Proxmox API token scoped to the permissions your workflows need, then copy the example config:
cp proxmox-config/config.example.json proxmox-config/config.json
The README lists the minimum keys as proxmox.host, proxmox.port, auth.user, auth.token_name and auth.token_value. An ssh section is required only for container command execution, and a jobs section only if you want job state somewhere other than the default SQLite file.
There are three runtime paths. For MCP over stdio, run uvx proxmox-mcp-plus, or pip install proxmox-mcp-plus followed by proxmox-mcp-plus. For native MCP HTTP in Docker, start the mcp-http profile with docker compose --profile mcp-http up -d proxmox-mcp-http and point clients at http://localhost:8000/mcp. For the OpenAPI bridge, run docker compose up -d and check curl -f http://localhost:8811/livez. The README gives a direct docker run example with PROXMOX_MCP_MODE=mcp-http, MCP_HOST=0.0.0.0, MCP_PORT=8000, MCP_TRANSPORT=STREAMABLE_HTTP and MCP_API_KEY, mounting the config file read-only at /app/proxmox-config/config.json.
One detail deserves attention. The README states that if MCP_API_KEY is unset, Streamable HTTP "remains unauthenticated for backward compatibility and logs a security warning at startup." The default is open, and the warning is a log line, not a refusal to start. Anyone exposing that port beyond localhost without setting the key is running an unauthenticated control plane for their hypervisor.
Tool filtering, and why an empty allowlist is the safe mistake
Every MCP tool schema sent to a client consumes context and widens the surface an agent can act on. The project offers tool_allowlist and tool_denylist under the mcp config key, plus the MCP_TOOL_ALLOWLIST and MCP_TOOL_DENYLIST environment variables. Filtering is disabled by default, so an existing configuration keeps exposing every tool after an upgrade.
Several behaviours here are worth stating precisely because they determine whether a mistake is loud or silent. Configure exactly one mode; the README says not to configure both. Environment selection replaces the file-level filtering mode rather than merging with it. An empty allowlist exposes no tools, while an empty denylist hides none. Exact lowercase tool names are required, and unknown names fail startup, which is the right call: a typo in a denylist entry would otherwise leave a tool exposed while the operator believed it was blocked. After changing the filter you must restart or reconnect the MCP server.
The example allowlist is ["get_nodes", "get_vms", "get_containers", "get_storage"], which is read-only inspection. That is a reasonable starting point for a new agent integration, and it is worth staying there until you have watched the agent's tool calls in a non-production context.
Where the safety model has soft edges and hard limits
The safety features listed include Proxmox API tokens, OpenAPI bearer auth, command policy, approval tokens, TLS validation, and MCP HTTP Host and Origin controls. Two of these are documented well enough in the README to act on. DNS rebinding protection is on by default, and the reverse-proxy example sets MCP_DNS_REBINDING_PROTECTION=true with MCP_ALLOWED_HOSTS=mcp.example.com:*,localhost:* and MCP_ALLOWED_ORIGINS=https://mcp.example.com. Command policy and approval tokens are named but not specified in the material supplied here, so I cannot describe how they decide what to allow, whether approval tokens expire, or what the default policy permits. That is a documentation gap, and it is a gap in the part of the system where guessing is most expensive.
The larger limitation is structural. The project needs network access to the Proxmox API and, for container commands, SSH access to the target. It cannot work offline, and it cannot be the only path to a host that has no other management route, because the thing you would use to fix a broken Proxmox node is the thing that depends on that node answering. Keep working SSH and the Proxmox web UI available regardless of what the agent can do.
A second limitation is version churn. Three releases appear in the supplied material within roughly a month, v0.5.13 on 2026-08-10, v0.5.14 on 2026-08-11 and v0.5.15 on 2026-09-04. Rapid point releases are normal for a young project, but they mean the tool list and config keys are a moving target. Pinning a version in production is the obvious response, and it is worth reading the release notes before moving the pin.
How it differs from the Proxmox API directly or a Terraform workflow
The alternative most operators already have is the Proxmox REST API itself, called from a shell script or a small Python client. That approach gives complete control and no dependency on a third-party wrapper. What it does not give you is a tool schema an LLM can use, a stable job_id abstraction over Proxmox UPIDs, or a single place to apply an allowlist. If your automation is deterministic and runs on a schedule, the raw API plus a script is simpler and has one less component to keep updated. ProxmoxMCP-Plus earns its place when the caller is an agent that decides at runtime which operation to invoke.
A second alternative is an infrastructure-as-code tool such as Terraform's Proxmox provider, which models desired state and reconciles it. That is a declarative approach: you describe the VM you want and the tool makes reality match. ProxmoxMCP-Plus is imperative and conversational. It takes a snapshot, starts a container, downloads an ISO, and reports a job id. These are different jobs. Terraform is the wrong instrument for "take a snapshot before I patch this box," and ProxmoxMCP-Plus is the wrong instrument for managing a fleet's declared configuration. Running both is reasonable, but they should not be pointed at the same resources without a clear owner for each.
Licence, maintenance cost and what to check before adopting
The project is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is a permissive licence with few obligations, and it is the same licence used by a large share of Python tooling. It does not come with any warranty, and the MIT text disclaims liability, so the operational risk of an agent taking a wrong action on a hypervisor sits with you and not with the author. None of this is legal advice; read the LICENSE file in the repository if the terms matter to your organisation.
Maintenance cost has three components. First, the version pin: the release cadence shown in the supplied material means you should track releases deliberately rather than pulling latest. Second, the credential surface: a Proxmox API token, an SSH key or credentials for container commands, an OpenAPI bearer key and an MCP API key, each with its own rotation schedule. Third, the SQLite job database, which needs a persistent path and a backup policy if audit history matters to you.
Before adopting, verify that your MCP client can list the expected tools after connecting, that your chosen filter mode starts cleanly and rejects unknown tool names, and that the Proxmox token you created is scoped to the operations you intend to allow rather than to the whole cluster. The README also mentions proxmox-config/config.live.json and proxmox-config/config.live.example.json for live end-to-end verification, with an explicit warning not to point live tests at a placeholder or local-only config. If you intend to run those tests, set up a disposable VM or container as the target first. Testing snapshot rollback against a production guest is not a verification step; it is an incident.
Editorial conclusion
Adopt ProxmoxMCP-Plus if you run Proxmox VE at homelab or small-cluster scale and want an AI client or an HTTP script to drive day-2 operations without writing a Proxmox API wrapper yourself. Do not adopt it if you need offline operation, if you cannot expose the Proxmox API token to the process running the server, or if you expect the tool list to be stable across upgrades. Verify three things before you trust it: that MCP_API_KEY is set and not left unset, that your Proxmox API token is scoped to the operations you actually intend to allow, and that your chosen allowlist or denylist starts and rejects typos as the README states.
Community notes