Proxmox MCP broker
Provides tools for operating a Proxmox VE cluster, including inventory/status checks, guest lifecycle operations, snapshots, and tiered administrative actions such as cloning, configuration, disks, migration, firewalls, pools, HA, backup jobs, and SDN.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Proxmox MCP broker
This repository lets Claude operate a Proxmox VE cluster through the Model Context Protocol (MCP), behind Cloudflare Access, with per-person accountability.
It is a fork of ry-ops/proxmox-mcp-server
by ry-ops (MIT license), imported at upstream commit 7276144. The 340 Proxmox tools
and their handlers are the upstream code. This fork adds the security layers around
them: identity, policy, per-user API tokens, verified TLS, output filters and a
hash-chained audit log.
Contents
Related MCP server: proxmox-mcp
Setup
The deployment works with any Proxmox VE 8 or 9 cluster, any Cloudflare account with Zero Trust, and a Windows Server 2025 host for the broker. One file holds every value of your deployment, and one command turns it into the exact ordered steps.
AI agents: read AGENTS.md first. It holds the rules and the workflow.
Prerequisites
Where | What you need |
Proxmox VE | Root shell on one node (SSH). A resource pool for the guests the AI may see. |
Broker host | Windows Server 2025, BitLocker with TPM, outbound HTTPS and UDP/TCP 7844, a route to the Proxmox API port. No inbound port. |
Cloudflare | Zero Trust with an identity provider that enforces MFA, an MCP Server Portal, a zone for two host names, Workers (Standard plan), R2. An API token with the permissions in the header of |
Azure (or equal) | A storage container with a locked time-based retention policy for the audit log. |
Workstation | Python 3.11 or later, |
Legal | If any guest in scope can hold PHI: signed BAAs with Cloudflare and Anthropic. |
Steps
Copy the template and fill it. The copy is git-ignored. Put no secret in it.
cp deploy/provision.example.toml deploy/provision.tomlValidate it and print the plan:
python3 deploy/plan.py deploy/provision.toml # numbered steps with exact commands python3 deploy/plan.py deploy/provision.toml --json # the same plan for an AI agentRun the steps in order. Each step names where it runs, who runs it, and the check that must pass before the next step:
Phase
Where
What
0 preflight
you
Change approval, MFA policy, BAAs if PHI is in scope
1 build
workstation
Build the wheel, check the hashed lock, hash the downloads
2 proxmox
Proxmox node
Roles and pool, one user per person, read the TLS pin
3 broker
broker
Host baseline, broker install, cloudflared, firewall
4 credentials
node to broker
One API token per person, piped into DPAPI; enrollment
5 cloudflare
workstation
Tunnel, Access apps, Worker, R2 lock, portal entry
6 activate
broker
Second install pass with the Access values, key escrow, audit shipping
7 verify
broker and Claude
Test-ProxmoxMcpBroker.ps1 -Live, 401 check, first read from ClaudeSecrets never pass through a file, a chat or a command line. Proxmox tokens go from the node straight into the broker's DPAPI store. The Cloudflare API token is typed at a hidden prompt. The plan marks every such step
HUMAN, SECRET.
docs/RUNBOOK.md explains each step in detail, and covers day-2 tasks: enroll a person, rotate a token, revoke access, emergency off.
Architecture
The system has two parts on two sides of a trust boundary:
The Cloudflare Worker (
worker/) is the inbound gateway. It speaks MCP to Claude. It holds no Proxmox credential.The broker (this Python package) is the outbound gateway. It runs on an on-premises Windows Server host. It holds the Proxmox API tokens and makes the final policy decision.
Claude (claude.ai, Desktop, Code)
|
| HTTPS, OAuth (Cloudflare Access Managed OAuth, Entra ID with MFA)
v
Cloudflare MCP Server Portal + Access application (named users only)
|
v
Cloudflare Worker https://<worker-hostname>/mcp
| - verifies the Access JWT again (RS256, team keys, issuer, audience)
| - JSON-RPC allowlist, size cap, per-user rate limit
| - 3 meta-tools: list_tools, describe_tool_input, execute_tool (MCP-STD-02)
| - signs an Ed25519 identity assertion for each broker call
| - redacts secrets and PHI patterns, labels results as untrusted data
|
| Workers VPC binding, or Access service token, over a Cloudflare Tunnel
v
cloudflared (Windows service, outbound connections only)
|
v
Broker http://127.0.0.1:<port> GET /healthz, GET /v1/catalog, POST /v1/execute
| - verifies the Access service-token JWT (the caller is the Worker)
| - verifies the identity assertion (signature, 60 s life, body hash, replay cache)
| - enrollment: user email -> mode (ro, operator, rw) and Proxmox token
| - tool policy, strict argument validation, rate limit
| - upstream tool handler
| - outbound policy: method and path allowlist per mode, deny list, PHI check
| - audit: one hash-chained JSON line per event, no argument values
|
| HTTPS, TLS 1.2 or later, CA bundle or SHA-256 certificate pin
v
Proxmox VE API https://<proxmox-host>:8006 (one privilege-separated token per person)The Proxmox API tokens never leave the broker host. Cloudflare holds no Proxmox credential. The broker holds only the public half of the Worker signing key, so a broker compromise cannot forge identities.
Read docs/ARCHITECTURE.md for the full design.
Security model
Each layer fails closed. A later layer does not trust an earlier layer.
Layer | Control | Where |
Person | Entra ID login with MFA. Access policy names each user. | Cloudflare Access |
Session | Access token 10 min. OAuth session 8 h. Identity assertion 60 s. | Access, Worker |
Gateway | JWT verified again, JSON-RPC allowlist, 256 KB cap, rate limit. |
|
Broker entry | Service-token JWT, Host allowlist, no Origin, 256 KB cap. |
|
Identity | Ed25519 assertion bound to body, method and path. Single use. |
|
Access list |
|
|
Tool policy | Every tool has a tier. Unknown tools are forbidden. |
|
Arguments | Strict JSON Schema check. Path values have fixed patterns. |
|
Outbound | Method and path allowlist per mode. DELETE needs rw. Deny list for tokens, TFA, consoles, guest agent exec. |
|
PHI | Writes that contain PHI patterns are refused. Results are redacted. |
|
Proxmox | One privilege-separated API token per person. Proxmox ACLs limit each token. | Proxmox VE |
TLS | Verified chain or SHA-256 pin. No redirects. No proxy settings from the environment. |
|
Output | Secret fields redacted. 2 MiB cap. Untrusted-data label on every result. |
|
Audit | Hash-chained JSONL with user, ray ID, tool, method, path, status. Keys and a hash of arguments, never values. |
|
Secrets are files, not environment variables. On Windows they are in the broker credentials directory, protected by DPAPI and by an ACL for the service account. On Linux they are systemd credentials.
Read docs/SECURITY.md for the threat model and risk register.
Modes and tool tiers
Each tool has one tier. Each enrolled person has one mode.
Tier | Tools | What it covers |
read | 133 | GET only: inventory, status, configuration, task logs. |
operate | 16 | Reversible guest lifecycle: start, stop, shutdown, reboot, reset, suspend, resume, snapshot create. |
admin | 85 | Guest create, clone, delete, configuration, disks, migration, guest firewall, pools, HA, backup jobs, SDN, raw host logs. |
forbidden | 106 | Never available: users, tokens, ACLs, TFA, passwords, consoles, guest agent exec and files, cloud-init user data, host power and network, host disks, cluster firewall, certificates, storage definitions, notification endpoints. |
Mode | Tiers | Tools |
ro | read | 133 |
operator | read, operate | 149 |
rw | read, operate, admin | 234 when |
The default for every new person is ro. Admin tools stay off until the operator
sets MCP_ALLOW_ADMIN_TOOLS=1 on the broker. MCP_TOOL_DENY and MCP_TOOL_ALLOW
can restrict the set more. They cannot add a tool.
Compliance gate
This build is designed for HIPAA Security Rule and SOC 2 audits.
Go-live gate. Protected health information (PHI) can pass through Cloudflare and Anthropic. Do not connect a system that holds PHI until a Business Associate Agreement (BAA) is signed with both Cloudflare and Anthropic.
The tools that read guest content are forbidden, and PHI patterns are redacted and refused on writes. These controls reduce exposure. They do not replace the BAA.
Read docs/COMPLIANCE.md for the control map and the evidence that an auditor collects.
Configuration
The broker reads its settings from environment variables and its secrets from the
credentials directory. .env.example lists every setting with a
safe example value. Do not put a token or a password in .env.
The credentials directory contains:
File | Content |
| The access list: email, mode, Proxmox user ID, name of the token file. |
| One line: |
| The Worker's Ed25519 public key (PEM). |
Example enrollment.json:
{
"users": {
"alice@example.com": {
"mode": "ro",
"proxmox_userid": "mcp-alice@pve",
"token_credential": "pve-token-alice"
}
}
}Read docs/RUNBOOK.md to install the broker, enroll a person, rotate a token, and stop the service in an emergency.
Local development
You can run the upstream stdio server on a workstation, against a lab cluster:
uv venv -p 3.14 .venv
uv pip install -p .venv -e . pytest pytest-asyncio ruff
export PROXMOX_HOST=pve.example.internal
export PROXMOX_TLS_FINGERPRINT=<sha256-of-the-proxmox-certificate>
export PROXMOX_USER=dev@pve PROXMOX_TOKEN_NAME=mcp
read -rs PROXMOX_TOKEN_VALUE && export PROXMOX_TOKEN_VALUE
.venv/bin/proxmox-mcp-serverThe stdio server runs as the local identity. Its mode is MCP_LOCAL_MODE
(default ro). Use a lab token with few privileges. Do not use stdio mode on the
broker host.
Tests
.venv/bin/pytest -q --no-cov
.venv/bin/ruff check proxmox_mcp testsThe tests run offline. The end-to-end tests (tests/test_e2e_*.py) start the real
broker application with a temporary credentials directory and drive it as the
Worker does. They execute every tool as ro, operator and rw, and check that:
the decision agrees with the tool tier;
a denied call never reaches Proxmox;
an allowed call reaches Proxmox only with the caller's own token, and makes the same Proxmox calls as the upstream handler (
tests/fixtures/upstream_calls.json);each result has the untrusted-data label, and secrets and PHI are redacted;
the audit log has one line for each side, and the hash chain is intact.
tests/test_e2e_tls.py uses a real local TLS server with a pinned self-signed
certificate. With a wrong pin, no request byte reaches the server.
Documents
Document | Content |
Rules and provisioning workflow for AI agents. | |
Template of every deployment value. | |
Components, data path, trust boundaries. | |
Threat model and risk register. | |
HIPAA and SOC 2 control map with evidence. | |
Installation, operation, incident response. | |
The Cloudflare Worker. | |
How Claude finds and runs tools. | |
Changes by version. |
Changes from upstream
The tool handlers are unchanged, with one fix:
analyze_scheduleuses GET, as the Proxmox API defines it.Removed: password and ticket authentication,
PROXMOX_VERIFY_SSL, one shared token for all users, and the stdio container as a deployment.Added: the broker HTTP API, identity assertions, enrollment, tool tiers, outbound policy, PHI filter, output redaction, the audit log and the
worker/gateway.setup.shandtest-connection.shno longer write or use secrets. They point to the runbook.PROXMOX_READ_ONLY=truestill works. It is a kill switch for all writes on top of the modes.
Credits and license
The Proxmox tools, their schemas and their handlers are the work of ry-ops in proxmox-mcp-server. Thank you.
MIT license. See LICENSE. The copyright notice of ry-ops stays in
LICENSE and applies to the upstream code and to this fork.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Governed MCP gateway: one endpoint for your tools, with credential custody and audit log.
Identity, authorization, audit trails, and revocable permissions for AI agents accessing MCP tools.
Connect ChatGPT and Claude to your Mac, Windows or Linux with secure MCP remote access.
One MCP endpoint for your company's tools, with per-person sign-in, policy and audit.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables Claude to manage Proxmox VE infrastructure — VMs, LXC containers, snapshots, storage, and more.372MIT
- AlicenseAqualityDmaintenanceEnables LLM agents to monitor and manage a Proxmox VE cluster, including cluster status, VM/container lifecycle, and node actions via MCP tools.8MIT
- AlicenseNot gradedqualityDmaintenanceEnables Claude to manage a Proxmox VE host through natural language, including guest lifecycle, snapshots, host status monitoring, and shell execution via a companion bridge.22 npm1Apache 2.0
- AlicenseNot gradedqualityNot gradedmaintenanceEnables Claude to manage a Proxmox cluster through chat: inventory, power control, configuration changes, VM/container creation and cloning, snapshots, network/firewall/cluster visibility, guest command execution, and file writes via the QEMU Guest Agent.22 npmMIT