ProxmoxMCP-Plus

Why ProxmoxMCP-Plus

ProxmoxMCP-Plus sits 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.

It exposes the same operational surface in two ways:

• MCP for Claude Desktop, Cursor, VS Code, Open WebUI, Codex, and other MCP-capable agents

• OpenAPI for HTTP automation, dashboards, internal tools, and no-code workflows

What you get:

• 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

• persistent job tracking for async Proxmox tasks

Related MCP server: mcp-proxmox

What Makes It Different

Quick Start

1. Prepare Proxmox Credentials

Create a Proxmox API token with only the permissions your workflows need. Then create the local config file:

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

Then edit proxmox-config/config.json with your environment. At minimum, it needs:

• proxmox.host

• proxmox.port

• auth.user

• auth.token_name

• auth.token_value

Add an ssh section as well if you want container command execution. Add a jobs section if you want job state persisted somewhere other than the default local SQLite file.

For real live verification, use a separate proxmox-config/config.live.json created from proxmox-config/config.live.example.json. Do not point live e2e at a placeholder or local-only config.json unless you intentionally run a local API tunnel there.

Optional job persistence config:

{
  "jobs": {
    "sqlite_path": "proxmox-jobs.sqlite3"
  }
}

Optional tool exposure filtering can reduce the schemas sent to MCP clients. It is disabled by default, so existing configurations continue to expose every available tool. Configure exactly one mode under mcp:

{
  "mcp": {
    "tool_allowlist": ["get_nodes", "get_vms", "get_containers", "get_storage"]
  }
}

Alternatively, use tool_denylist, or the comma-separated environment variables MCP_TOOL_ALLOWLIST and MCP_TOOL_DENYLIST. Do not configure both modes. Environment selection replaces the file-level filtering mode. An empty allowlist exposes no tools; an empty denylist hides none. Exact lowercase tool names are required, and unknown names fail startup so a typo cannot silently widen access. Restart or reconnect the MCP server after changing the filter.

2. Choose One Runtime Path

MCP stdio with PyPI

uvx proxmox-mcp-plus

Or install it first:

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

Use this path when the MCP client launches a local stdio server.

Code Mode (opt-in)

Code Mode is disabled by default to preserve the legacy full tool catalog. Enable it with mcp.code_mode: true in the config file or MCP_CODE_MODE=true. When enabled, MCP exposes three tools instead: proxmox_code_search, proxmox_code_get_schema, and proxmox_code_execute. Code execution runs in an isolated sandbox and reaches domain tools through the existing validation, policy, and approval path. Discovery uses the filtered runtime catalog, so it also works in installed wheels. For example:

await call_tool("get_nodes", {"target": "default"})

The final expression is returned as data.result; tool results use MCP JSON content blocks (and structured content where supplied). Use proxmox_code_get_schema for arguments, including target and approval tokens. Scripts have no filesystem or network access except registered tool calls. Limits: 64,000 source characters, 100 MB sandbox memory, 25 tool calls, 16 KB final JSON, and two concurrent executions. Execution has a 30-second budget; cancelling or failing a script does not roll back tool side effects. Do not automatically retry a failed mutation script.

Optional worker reuse: set mcp.code_mode_pool_reuse: true or MCP_CODE_MODE_POOL_REUSE=true. The default remains one fresh worker per execution. Reuse keeps up to two workers for the server lifetime, recycles each after 100 checkouts, and starts a new sandbox session per request. Globals, approvals, output collectors and call limits are not shared between requests. HTTP clients share the server-owned pool; disconnecting a client does not close it. Run python scripts/benchmark_code_mode.py to measure local startup overhead; this is a microbenchmark, not an estimate of Proxmox operation latency.

Native MCP HTTP with Docker

Use this path when a remote MCP client supports Streamable HTTP:

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

Point MCP clients at:

http://<docker-host>:8000/mcp

Send Authorization: Bearer <MCP_API_KEY> with every native MCP HTTP request. The key is independent of Proxmox credentials. Native Streamable HTTP and SSE require a key by default. For an endpoint protected by an external access-control layer such as Tailscale ACLs, explicitly set MCP_ALLOW_UNAUTHENTICATED_HTTP=true or mcp.allow_unauthenticated_http: true in JSON configuration. This allows keyless startup and logs a warning; it does not configure or verify the external access controls. A configured MCP_API_KEY is always enforced, even with opt-out. This setting does not change OpenAPI authentication or DNS rebinding protection.

OAuth browser gate for MCP clients

Native MCP HTTP can optionally expose an OAuth authorization-code flow with PKCE while keeping MCP_API_KEY as the only human credential an operator has to manage. OAuth protocol handling is delegated to the MCP Python SDK (mcp>=1.30.0,<2), while ProxmoxMCP-Plus provides the API-key consent policy and persistent OAuth state.

OAuth state is stored in PostgreSQL. This allows multiple MCP workers or hosts to share registered clients, authorization codes, access tokens, refresh tokens, refresh-token replay protection, and login-rate-limit state without relying on a local filesystem.

The client starts at the SDK /authorize endpoint. After the SDK validates the client, redirect URI, scope, PKCE request, and resource, the browser is redirected to /oauth/consent on the same MCP origin. The user reviews the client name, redirect origin, and requested scopes, then enters MCP_API_KEY. The API key is never placed in a URL and is never returned to the OAuth client.

Required OAuth settings:

export MCP_API_KEY="$(openssl rand -hex 32)"
export MCP_OAUTH_DATABASE_URL='postgresql://proxmox_oauth:secret@postgres.example:5432/proxmox_oauth'

Example server:

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" \
  -e MCP_OAUTH_ENABLED=true \
  -e MCP_OAUTH_ISSUER=https://mcp.example.com \
  -e MCP_OAUTH_DATABASE_URL="$MCP_OAUTH_DATABASE_URL" \
  -e MCP_ALLOWED_HOSTS=mcp.example.com:*,localhost:* \
  -e MCP_ALLOWED_ORIGINS=https://mcp.example.com \
  -v "$(pwd)/proxmox-config/config.json:/app/proxmox-config/config.json:ro" \
  ghcr.io/rekklesna/proxmoxmcp-plus:latest

Then connect the OAuth-capable client to:

https://mcp.example.com/mcp

OAuth mode exposes these endpoints on the same public origin:

• /.well-known/oauth-protected-resource/mcp - RFC 9728 protected-resource metadata

• /.well-known/oauth-authorization-server - SDK authorization-server metadata

• /register - SDK dynamic client registration (DCR)

• /authorize - SDK authorization endpoint

• /token - SDK authorization-code/refresh-token exchange

• /oauth/consent - ProxmoxMCP-Plus API-key consent page

The SDK requires PKCE S256 and protects the MCP resource with issued OAuth access tokens. Browser consent transactions are short-lived, HMAC-signed, and stateless. All durable OAuth state is stored in PostgreSQL.

Authorization-code consumption and refresh-token rotation use PostgreSQL transactions. A code or refresh token is deleted and its replacement tokens are inserted atomically, so concurrent workers cannot successfully replay the same credential. Dynamic client registration capacity is also serialized with a PostgreSQL transaction-scoped advisory lock; inactive registrations are pruned before the configured limit is exceeded.

API-key rotation is versioned for multi-worker safety. MCP_OAUTH_KEY_VERSION defaults to 1. When changing MCP_API_KEY, increment the version at the same time on every new worker. A higher version atomically invalidates existing client registrations and their dependent codes/tokens. A worker with an older version is rejected, and workers using different keys with the same version are rejected. This prevents a stale worker from reversing a distributed key rotation.

Required when OAuth is enabled:

Optional OAuth environment variables:

To rotate the browser-gate credential, deploy the new key with a higher version, for example:

MCP_API_KEY=<new-secret>
MCP_OAUTH_KEY_VERSION=2

Do not reuse a version number for a different key.

The database role must be able to create and modify the proxmox_mcp_oauth_* tables in its database. The tables contain OAuth client metadata, including issued client secrets, plus authorization codes and active tokens, so the PostgreSQL database and backups must be protected as credential storage.

If several MCP instances use the same MCP_OAUTH_DATABASE_URL, OAuth state and one-time-token enforcement are shared across them. Size the pool with the total number of MCP workers in mind because the configured pool limits apply per process.

If the server is behind a trusted reverse proxy and per-user login rate limiting must use the original client address, set MCP_OAUTH_CLIENT_IP_HEADER to a header that the proxy overwrites (for example CF-Connecting-IP). Leave it unset unless the proxy prevents clients from spoofing that header.

When MCP_OAUTH_ENABLED=true, a raw Authorization: Bearer <MCP_API_KEY> request to /mcp is intentionally rejected. The API key is accepted only by the consent page; MCP requests must use an issued OAuth access token.

When serving MCP HTTP behind a reverse proxy, keep DNS rebinding protection enabled and allow only the hostnames you expect.

OpenAPI bridge with Docker

OpenAPI mode is the default Docker runtime and requires an API key:

export PROXMOX_API_KEY="$(openssl rand -hex 32)"
docker run --rm -p 8811:8811 \
  -e PROXMOX_API_KEY="$PROXMOX_API_KEY" \
  -v "$(pwd)/proxmox-config/config.json:/app/proxmox-config/config.json:ro" \
  ghcr.io/rekklesna/proxmoxmcp-plus:latest

Verify the OpenAPI surface:

curl -f http://localhost:8811/livez
curl -f -H "Authorization: Bearer $PROXMOX_API_KEY" http://localhost:8811/health
curl -H "Authorization: Bearer $PROXMOX_API_KEY" http://localhost:8811/openapi.json

For local unauthenticated development only, set PROXMOX_ALLOW_NO_AUTH=true.

Source checkout

git clone https://github.com/RekklesNA/ProxmoxMCP-Plus.git
cd ProxmoxMCP-Plus
uv venv
uv pip install -e ".[dev]"
python main.py

The 8811 service is the OpenAPI/REST bridge. The 8000 service is the native MCP HTTP endpoint.

Client Install

Use the one-click buttons when your client supports MCP install deeplinks, or copy the JSON config below.

Recommended stdio config:

{
  "mcpServers": {
    "proxmox-mcp-plus": {
      "command": "uvx",
      "args": ["proxmox-mcp-plus"],
      "env": {
        "PROXMOX_HOST": "your-proxmox-host",
        "PROXMOX_USER": "root@pam",
        "PROXMOX_TOKEN_NAME": "mcp-token",
        "PROXMOX_TOKEN_VALUE": "your-token-secret",
        "PROXMOX_PORT": "8006",
        "PROXMOX_VERIFY_SSL": "true"
      }
    }
  }
}

Use a local config file if you prefer not to keep credentials in the client config:

{
  "mcpServers": {
    "proxmox-mcp-plus": {
      "command": "uvx",
      "args": ["proxmox-mcp-plus"],
      "env": {
        "PROXMOX_MCP_CONFIG": "/path/to/ProxmoxMCP-Plus/proxmox-config/config.json"
      }
    }
  }
}

Client-specific examples for Claude Desktop, Cursor, VS Code, Codex, OpenCode, Open WebUI, Streamable HTTP, and OpenAPI are in the Client Setup Guide and Integrations Guide.

Demo

This demo is a direct terminal recording of qwen/qwen3.6-plus driving a live MCP session in English against a local Proxmox lab. It shows natural-language control flowing through MCP tools to create and start an LXC, execute a container command, and confirm the authenticated HTTP /health surface.

Watch the MP4 version

Choose The Right Tool

Start with read-only discovery, then move to mutating tools only after the target node, storage, VMID, and permissions are clear.

For the full tool map, see the Tool Selection Guide and API & Tool Reference.

Safety Model

ProxmoxMCP-Plus is an access layer, not a replacement for Proxmox RBAC, network controls, or client-side MCP approval prompts.

The project gives operators several control points:

• Proxmox API tokens decide what the backend can do.

• PROXMOX_API_KEY protects the OpenAPI bridge by default.

• MCP_API_KEY protects native Streamable HTTP and SSE with Bearer authentication; it is required unless MCP_ALLOW_UNAUTHENTICATED_HTTP=true explicitly delegates access control.

• TLS verification is enforced unless development mode is explicitly enabled.

• command_policy controls command execution and high-risk operations.

• approval_token can gate command execution and high-risk mutating actions.

• MCP Streamable HTTP deployments can use DNS rebinding protection plus Host and Origin allowlists.

• Optional MCP tool allowlists or denylists reduce the runtime tool surface; they do not replace Proxmox RBAC.

• Logs are designed to avoid exposing command and credential material.

Read the Security Guide before exposing the server outside a trusted local environment.

Core Platform Capabilities

ProxmoxMCP-Plus provides a unified control surface for the operational tasks most teams actually need in Proxmox VE. The same server can expose these workflows to MCP clients for LLM and AI-agent use cases, and to HTTP consumers through the OpenAPI bridge.

Supported workflow areas:

Validation and contract entry points in this repository:

• pytest -q --cov=proxmox_mcp --cov-report=term-missing --cov-fail-under=75

• ruff check .

• mypy src --ignore-missing-imports

• pip-audit -r requirements.txt

• tests/integration/test_real_contract.py

• tests/scripts/run_real_e2e.py

tests/scripts/run_real_e2e.py now prefers proxmox-config/config.live.json or PROXMOX_MCP_E2E_CONFIG. This avoids accidentally running live checks against a machine-specific default config.json.

Long-Running Jobs

Many Proxmox mutations are asynchronous. ProxmoxMCP-Plus now wraps those tasks in a persistent job layer so MCP and OpenAPI clients can track them through a stable Job ID.

Long-running tools such as VM create/start/stop, container create/start/stop, snapshot changes, backup/restore, and ISO download/delete now return both:

• task_id: the raw Proxmox UPID

• job_id: the stable server-side job record

The job record stores:

• current status and progress

• retry count and prior UPIDs

• latest result payload or failure reason

• audit history for create, poll, retry, and cancel actions

By default the job store persists to proxmox-jobs.sqlite3, so restart does not lose in-flight or completed job metadata.

Audit events are appended to a separate SQLite table. Existing history is migrated on startup and the API's audit_log format stays unchanged. Retention is unlimited by default; set jobs.audit_retention_days to a positive number in JSON config to prune expired events at startup and when each job is updated. This never deletes the job itself. Stop all workers sharing the database and back it up before this upgrade. Do not run old and new versions against the same database; restore the pre-upgrade backup if downgrading and retaining audit history is required.

A cancellation request is not completion. Poll until the task is failed/cancelled before calling retry_job; pending cancellation cannot be retried.

MCP Job Tools

• list_jobs

• get_job

• poll_job

• cancel_job

• retry_job

OpenAPI Job Routes

When the OpenAPI proxy is enabled and a local JobStore is available, these routes are exposed directly:

Common error codes:

• 404: unknown job_id

• 409: the job exists but that operation is not valid now

• 503: the OpenAPI proxy was started without a local JobStore

tests/scripts/run_real_e2e.py now prefers proxmox-config/config.live.json or PROXMOX_MCP_E2E_CONFIG. This avoids accidentally running live checks against a machine-specific default config.json.

Positioning Against Common Approaches

Scenario Templates

Ready-to-copy examples live in docs/examples/:

• Create a test VM

• Roll back a risky change with snapshots

• Download an ISO and create an LXC

These are written for both human operators and LLM-driven usage.

Documentation

The README is intentionally optimized for fast GitHub comprehension. Longer operational docs live in docs/wiki/ and can also be published to the GitHub Wiki.

Published wiki:

• GitHub Wiki Home

Repo Layout

• src/proxmox_mcp/: MCP server, config loading, security, OpenAPI bridge

• main.py: MCP entrypoint for local and client-driven usage

• docker-compose.yml: HTTP/OpenAPI runtime

• requirements/: auxiliary dependency sources and runtime install lists

• scripts/: helper startup scripts for local workflows

• tests/scripts/run_real_e2e.py: live Proxmox and Docker/OpenAPI path

• tests/: unit and integration coverage

• docs/examples/: scenario-driven prompts and HTTP examples

• docs/wiki/: longer-form operator, integration, and reference docs

Development Checks

pytest -q --cov=proxmox_mcp --cov-report=term-missing --cov-fail-under=75
ruff check .
mypy src --ignore-missing-imports
pip-audit -r requirements.txt
python -m build

Paramiko 5.0.0 or newer is required so pip-audit can run without a CVE-2026-44405 exception.

License

MIT

ISO installation and LXC network configuration

Use list_isos to find an existing ISO volume (or download_iso to obtain one). create_vm accepts iso_volume="local:iso/debian.iso", mounts it on ide3 by default and boots CD-ROM before disk. update_vm_config can mount or change that ISO, eject with iso_volume="none", set boot_order="scsi0;ide3", or change network_bridge on net0 while retaining MAC/VLAN/firewall settings. Choose a free cdrom_device; existing data disks and cloud-init drives are never replaced. Media and bridge edits read current configuration and therefore need VM.Audit as well as the relevant configuration privileges. Existing sizing/cloud-init-only updates still do not require a preliminary read.

LXC uses OS templates, not installer ISOs. create_container retains DHCP by default and now accepts network_bridge, ip="192.168.1.50/24", gw="192.168.1.1", ip6 and gw6. update_container_network edits those fields on an existing interface (default net0, selectable through net31) and preserves all unspecified options. Use an empty gateway string to remove it; changing to DHCP/manual removes the old gateway for that address family. Network changes can interrupt guest connectivity. Both edit tools follow named-target, read-only and high-risk approval policies. Add update_container_network to custom high-risk lists and desired tool allowlists. See v0.5.19 release notes for upgrade details.