Model or dataset
RekklesNA/ProxmoxMCP-Plus avatar
RekklesNA/ProxmoxMCP-Plus

ProxmoxMCP-Plus: an empty MCP key beside a required one, and ruff capped below 0.2

Use MCP and OpenAPI to safely control Proxmox VE VMs, LXCs, backups, and snapshots from LLMs and AI agents.

653 stars103 forksPythonMIT

At a glance

What is it?
ProxmoxMCP-Plus puts an MCP server and an OpenAPI bridge in front of Proxmox VE, with tool filtering, approval tokens and an optional code-execution mode. The deployment defaults disagree with each other, and the packaging keeps its metadata in two files.
Who is it for?
Use ProxmoxMCP-Plus if you want an agent-facing control plane for a Proxmox cluster with real guardrails, since the approval-token path, the fail-on-unknown tool filter and the explicit instruction not to retry failed mutations are better than most wrappers of this kind. Do not deploy the compose file as written on a reachable host: the MCP HTTP service binds all interfaces, defaults to requiring authentication, and defaults the key to an empty string.
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 2 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 November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • RekklesNA/ProxmoxMCP-Plus653 ★ · +126
Star history
Repository2026-09-112026-11-15
RekklesNA/ProxmoxMCP-Plus527653

126 Stars in the last 65 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Two build backends carry the same version and the same eleven dependencies by hand

The modern build path is declared in `pyproject.toml`, which names hatchling as the build backend. Alongside it sits a `setup.py` that says in its own docstring that it is maintained for compatibility with older tools and exists for tools that do not support pyproject.toml.

What that shim duplicates is the problem. It repeats the version `0.5.24`, the same eleven runtime dependencies in the same order with the same bounds, the same dev extra, and the same two console scripts. The two copies are in agreement today. Nothing visible keeps them that way, and the version is a string typed twice, which is the classic place for a release to be half-published.

The shim also carries an author email that is a placeholder: `author_email="[email protected]"`. The modern manifest lists an author by name with no email at all. So a reserved example domain is the contact address on one of the two metadata paths.

There is a third dependency declaration besides the two. `requirements.txt` contains exactly one line, `-r requirements/runtime.txt`, and the `requirements/` directory holds whatever that file lists. So there are three lists to reconcile: the manifest, the setup shim, and the requirements tree. Nothing visible states which one the container build uses.

For a user, none of that is visible. The documented install is one line, run through uv:

bash
uvx proxmox-mcp-plus

or installed first and then run:

bash
pip install proxmox-mcp-plus
proxmox-mcp-plus

Which of the three metadata sources feeds that wheel is decided somewhere in the build configuration, and the shim's own docstring says as much when it points readers to the modern manifest instead.

ruff is capped below 0.2 next to a current black, and the test HTTP client is not httpx

The development extra is where the version policy gets inconsistent.

`black` is `>=24.3.0,<27.0.0` and `mypy` is `>=1.0.0,<2.0.0`, both spanning years of releases. `pytest` is `>=9.0.3,<10.0.0` and `build` is `>=1.2.0,<2.0.0`. Then there is `ruff>=0.1.0,<0.2.0`, a range that covers the earliest 0.1 releases and excludes every ruff since.

So a developer installing the dev extra gets a linter from a different era than the formatter sitting beside it in the same list. Whether that is deliberate, because a newer ruff changed a rule the project relies on, or an oversight nobody revisited, the result is the same: the pinned range will not move on its own.

The name to check twice is `httpx2>=2.0.0,<3.0.0`. The HTTP client an async test suite normally uses is `httpx`, and this list says `httpx2`. Whatever that package is, it is not the one the name suggests, and it is a test-only dependency, so the failure mode is a resolution problem rather than a runtime one.

The type stubs are present and specific: `types-paramiko` pinned to a dated build and `types-requests` matching the runtime range. So the typing story is deliberate while the linting story is not.

PostgreSQL is a required runtime dependency that the configuration documentation never mentions

One runtime dependency has no counterpart anywhere in the documented configuration.

`asyncpg>=0.30.0,<1.0.0` is an asynchronous PostgreSQL driver, and it is not optional. It sits in the main dependency list beside the MCP SDK, proxmoxer, requests, pydantic, fastapi, uvicorn, mcpo, paramiko, anyio and one exactly-pinned package.

The configuration documentation describes job persistence as a SQLite decision. You are told to add a `jobs` section if you want job state persisted somewhere other than the default local SQLite file, and the optional block shown sets a `sqlite_path`. That is the entire documented persistence surface.

So the picture is a SQLite default, an unstated alternative backend, and a mandatory PostgreSQL driver in the install. The practical consequence for anyone evaluating this is size and risk: a Proxmox bridge that only needs a local job file pulls an async database driver and its native dependencies onto the host, and an operator reading the configuration reference would have no way to know that.

One related detail in the same list. Ten of the eleven runtime dependencies float within explicit bounds, and one is pinned exactly: `pydantic-monty==0.0.22`. A `0.0.x` version carries no compatibility promise by its own numbering, and pinning it to a patch means no update ever arrives on its own.

The MCP HTTP service binds every interface, requires authentication, and defaults the key to empty

Three environment lines decide who can reach the MCP HTTP service.

`MCP_HOST=0.0.0.0` and `MCP_PORT=8000` bind all interfaces, and the compose port mapping publishes `8000:8000` with no interface restriction. `MCP_ALLOW_UNAUTHENTICATED_HTTP` defaults to `false`. And `MCP_API_KEY` defaults to an empty string.

So the shipped default is a service reachable from the network, with authentication required, and no key configured. The documentation does not say what an empty key does in that state. It might reject every request, which would make the default merely useless, or it might treat the empty value as absent and fall through to a path where the unauthenticated flag decides, which would make the default a wide-open API in front of a hypervisor. Both readings are consistent with the three lines shown, and the difference between them is the difference between a broken default and a serious one.

The comment above those lines says the unauthenticated flag is optional but strongly recommended for every remotely reachable deployment, which describes the flag as if it were the thing to set rather than the thing to leave alone.

The documented path does set a key, by generating one with `openssl rand -hex 32` before the `docker run`. So the fix is documented. What is not documented is the behaviour of the default you get if you skip that step, which is the case the compose file is written to survive.

The OpenAPI service refuses to start without a key, and the MCP service does not

The two services in one compose file enforce credentials differently, and the difference is visible in a single character of syntax.

The OpenAPI bridge writes its key requirement with compose's mandatory-variable form:

`PROXMOX_API_KEY=${PROXMOX_API_KEY:?Set PROXMOX_API_KEY before starting OpenAPI mode}`

That form makes the container fail to start when the variable is unset, with the message inline in the file. It is the correct pattern for a secret that has no sensible default, and it means nobody can bring up the HTTP API bridge unauthenticated by forgetting an environment variable.

The MCP HTTP service, twenty lines below in the same file, uses the ordinary default form instead: `MCP_API_KEY=${MCP_API_KEY:-}`. Same file, same secret, same project, opposite enforcement. One service fails loudly, the other starts quietly with nothing set.

The rest of the two service definitions is symmetric and sensible. Both mount the configuration directory read only at `/app/proxmox-config:ro` and point at the same config file through `PROXMOX_MCP_CONFIG`. The OpenAPI service also sets `API_HOST=0.0.0.0` and `API_PORT=8811`, adds a health check against `/livez` on a thirty-second interval, and carries `restart: unless-stopped`. The MCP service adds `PROXMOX_MCP_MODE=mcp-http` and `MCP_TRANSPORT=STREAMABLE_HTTP` and sits behind a compose profile so it only starts when asked for.

An environment variable replaces file-level tool filtering instead of adding to it

The tool exposure filter is the best-specified part of this project, with one precedence rule worth reading twice.

You can filter in the config file with either `tool_allowlist` or `tool_denylist` under the `mcp` key, and the documentation is precise about the edge cases: an empty allowlist exposes no tools, an empty denylist hides none, exact lowercase names are required, and unknown names fail startup so a typo cannot silently widen access. That last behaviour is deliberate and correct. A filter that fails closed on a typo is the difference between a guardrail and a suggestion.

The same two lists are also available as comma-separated environment variables, `MCP_TOOL_ALLOWLIST` and `MCP_TOOL_DENYLIST`, and only one mode may be configured.

Then: environment selection replaces the file-level filtering mode.

Replace is the operative word. Setting `MCP_TOOL_ALLOWLIST` in the environment does not intersect with the allowlist in your config file, and it does not fail when the file also has one. The environment wins outright and the file's policy stops applying. In a deployment where the config file is mounted read only and reviewed, and the environment is set once in a shell or a service manager, that means the reviewed policy can be displaced by an environment variable that nothing flags as a conflict.

The other operational note is easy to miss: after changing the filter you have to restart or reconnect the MCP server.

Code Mode swaps the catalog for three tools and tells you not to retry a failed mutation

Code Mode is off by default, described as preserving the legacy full tool catalog, and enabled with `mcp.code_mode: true` or `MCP_CODE_MODE=true`.

When it is on, MCP stops exposing the domain tools individually. Three replace them: `proxmox_code_search`, `proxmox_code_get_schema`, and `proxmox_code_execute`. Code runs in an isolated sandbox with no filesystem or network access except registered tool calls, and it reaches the domain tools through the existing validation, policy and approval path rather than around it.

The limits are all numeric, which makes them auditable: 64,000 source characters, 100 MB of sandbox memory, 25 tool calls, 16 KB of final JSON, two concurrent executions, and a 30-second execution budget. The final expression comes back as `data.result`, and tool results use MCP JSON content blocks.

Two sentences in that paragraph are worth more than the rest of the feature. Cancelling or failing a script does not roll back tool side effects. And: do not automatically retry a failed mutation script.

That is a project telling its users, in its own documentation, that the obvious agent behaviour on error is the dangerous one here. A cancelled script may already have deleted a snapshot or restored a backup, and a retry compounds it. Very few agent frameworks state that as clearly.

Worker reuse is opt-in separately, keeping up to two workers for the server lifetime, recycling each after a hundred checkouts, and starting a fresh sandbox session per request so globals, approvals and output collectors are not shared. HTTP clients share the server-owned pool, so disconnecting a client does not reclaim it.

Four registry descriptors, an HTML comment carrying the MCP name, and an unexplained root main.py

The distribution surface is wide, and only some of it is machine-readable.

Four descriptor files sit at the root: `manifest.json`, `server.json`, `glama.json`, and `smithery.yaml`. Each targets a different MCP or agent directory, so the same server is listed in four places with four metadata files, and nothing visible states that they are generated from the manifest.

The MCP registry name is not in any of them as far as the visible documentation shows. It is in an HTML comment at the very top of the README: `<!-- mcp-name: io.github.RekklesNA/proxmox-mcp-plus -->`. Registry identity carried in a comment inside prose is workable and easy to break.

There is also a `.mcpbignore` for the bundle format, a `Dockerfile` beside a `docker-compose.yml`, and a `main.py` at the root while the source lives under `src/` with the setup shim using `packages=find_packages(where="src")`. A root-level entry point next to a src layout is either a convenience launcher or a leftover, and the visible material does not say which.

One boundary the visible compose excerpt cannot show you: it stops partway through an environment assignment for the OAuth refresh token TTL, so the rest of that variable, and whatever follows it in the file, is not in view. That is also where the OAuth block ends, so the consent flow described in the comments is the only account of it.

Editorial conclusion

Use ProxmoxMCP-Plus if you want an agent-facing control plane for a Proxmox cluster with real guardrails, since the approval-token path, the fail-on-unknown tool filter and the explicit instruction not to retry failed mutations are better than most wrappers of this kind. Do not deploy the compose file as written on a reachable host: the MCP HTTP service binds all interfaces, defaults to requiring authentication, and defaults the key to an empty string. Set both the API key and the OAuth settings deliberately, and read the tool-filter precedence rules before you rely on an allowlist, because an environment variable replaces file-level policy rather than adding to it. On the packaging side, treat the version in pyproject.toml as the one that matters and ignore the legacy setup.py.

Frequently asked questions

What does ProxmoxMCP-Plus expose?

VM and LXC lifecycle actions, snapshot create, rollback and delete, backup and restore workflows, ISO download and cleanup, node, storage and cluster inspection, SSH-backed container command execution with guardrails, and persistent job tracking for asynchronous Proxmox tasks. It is reachable over MCP or over OpenAPI.

How do I install and start ProxmoxMCP-Plus?

Copy the example configuration with `cp proxmox-config/config.example.json proxmox-config/config.json`, fill in at least host, port, user, token name and token value, then run `uvx proxmox-mcp-plus` or install it with `pip install proxmox-mcp-plus`. The compose file adds an OpenAPI bridge on port 8811 and an MCP HTTP service on port 8000.

Can I limit which tools an MCP client sees?

Yes. Configure exactly one of tool_allowlist or tool_denylist under the mcp key in the config file, or use the comma-separated MCP_TOOL_ALLOWLIST and MCP_TOOL_DENYLIST environment variables. Filtering is disabled by default, exact lowercase names are required, and unknown names fail startup.

What is Code Mode in ProxmoxMCP-Plus?

An opt-in mode, off by default, that replaces the domain tool catalog with three tools for searching, reading schemas and executing code in an isolated sandbox. Scripts have no filesystem or network access except registered tool calls, with limits of 64,000 source characters, 100 MB of memory, 25 tool calls, 16 KB of final JSON, and a 30-second budget.

What authentication does the ProxmoxMCP-Plus container use?

The OpenAPI bridge requires PROXMOX_API_KEY and refuses to start without it, and the MCP HTTP service requires authentication by default with MCP_API_KEY defaulting to an empty value. Both bind all interfaces. An OAuth plus PKCE browser gate is available, where the client never receives the API key.

How is ProxmoxMCP-Plus packaged?

The manifest builds with hatchling, declares Python 3.11 or newer, and is classified as alpha at version 0.5.24 with two console scripts pointing at one entry point. A legacy setup.py duplicates the version, the eleven runtime dependencies and the dev extra by hand for older tooling.

Official sources

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

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/rekklesna-proxmoxmcp-plus.svg)](https://hysenlabs.com/projects/rekklesna-proxmoxmcp-plus)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/rekklesna-proxmoxmcp-plus.svg)](https://hysenlabs.com/projects/rekklesna-proxmoxmcp-plus)

Was this useful?