ProxmoxMCP-Plus

<!-- mcp-name: io.github.RekklesNA/proxmox-mcp-plus -->

<div align="center"> <img src="docs/assets/logo-proxmoxmcp-plus.png" alt="ProxmoxMCP-Plus Logo" width="160"/> </div>

<p align="center"><strong>Operate Proxmox VE from MCP clients, AI agents, and OpenAPI tooling through one security-conscious control plane for VMs, LXCs, snapshots, backups, ISOs, container commands, and persistent long-running jobs.</strong></p>

<p align="center"> <a href="https://pypi.org/project/proxmox-mcp-plus/"><img alt="PyPI" src="https://img.shields.io/pypi/v/proxmox-mcp-plus"></a> <a href="https://github.com/RekklesNA/ProxmoxMCP-Plus/releases"><img alt="GitHub Release" src="https://img.shields.io/github/v/release/RekklesNA/ProxmoxMCP-Plus"></a> <a href="https://github.com/RekklesNA/ProxmoxMCP-Plus/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/RekklesNA/ProxmoxMCP-Plus/ci.yml?branch=main"></a> <a href="https://github.com/RekklesNA/ProxmoxMCP-Plus/pkgs/container/ProxmoxMCP-Plus"><img alt="GHCR" src="https://img.shields.io/badge/GHCR-container-blue"></a> <a href="LICENSE"><img alt="License" src="https://img.shields.io/github/license/RekklesNA/ProxmoxMCP-Plus"></a> </p>

<p align="center"> <a href="#quick-start">Quick Start</a> | <a href="#client-install">Client Install</a> | <a href="#demo">Demo</a> | <a href="#choose-the-right-tool">Tools</a> | <a href="#safety-model">Safety</a> | <a href="#scenario-templates">Scenarios</a> | <a href="#documentation">Docs</a> | <a href="https://github.com/RekklesNA/ProxmoxMCP-Plus/wiki">Wiki</a> </p>

Architecture: MCP and OpenAPI entry points, guarded target-aware tools, Proxmox VE, and persistent jobs

MCP and OpenAPI are alternative entry points into the same workflows and may run in separate processes. Solid arrows show requests and execution; dashed arrows show persisted job and audit state. Approval gates, SSH execution and MCP HTTP OAuth depend on configuration. Select the diagram to view it at full size.

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
• opt-in guarded Proxmox node SSH commands
• persistent job tracking for async Proxmox tasks

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

Docker examples publish host ports on 127.0.0.1 by default; Compose modes are opt-in. Set only the selected mode's key: MCP_API_KEY for native HTTP or PROXMOX_API_KEY for OpenAPI. See Compose deployment and upgrade notes for reverse proxies, tunnels, explicit LAN bindings and container recreation.

#### 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 127.0.0.1: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://127.0.0.1:8000/mcp

For remote clients, use the configured proxy/tunnel URL or explicitly widen the host binding as described in Docker deployment.

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 server instances or hosts, when deployed explicitly, 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)"
# Replace <password> with the database user's password.
export MCP_OAUTH_DATABASE_URL='postgresql://proxmox_oauth:<password>@postgres.example:5432/proxmox_oauth'

Example server:

docker run --rm -p 127.0.0.1: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 server instances 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.

MCP_API_KEY is the sole source of truth for the browser consent credential. This runtime does not persist the key or its verifier in PostgreSQL. The server process validates consent directly against the value supplied in its environment. If the service is explicitly deployed as multiple containers or instances, configure the same secret for each instance. Stop all instances before changing the key, then restart/recreate all of them with the new value before routing traffic again. Existing OAuth clients and issued tokens are independent of the browser-gate key and remain valid until they expire or are revoked.

Required when OAuth is enabled:

Optional OAuth environment variables:

To rotate the browser-gate credential, stop every MCP instance using this issuer, update MCP_API_KEY in the deployment environment, and restart/recreate all instances with the same new key. The environment is read when the provider starts; editing a running container's environment does not reload its key. No OAuth database metadata or key-version update is required. Pending consent transactions created with the previous key will no longer validate after every instance has restarted; already issued OAuth tokens remain governed by their normal lifetime and revocation rules. A rolling key change leaves old instances accepting the old key and causes consent requests routed between different-key instances to fail. There is no database guard to detect or disable a stale instance. Changing the browser-gate key does not revoke existing access tokens, refresh tokens, or authorization codes; use explicit revocation for compromised OAuth credentials.

When upgrading from an OAuth build that used MCP_OAUTH_KEY_VERSION, startup ignores the old variable and leaves proxmox_mcp_oauth_metadata untouched. Fresh databases do not create that table. Registered clients and issued OAuth credentials are preserved; no manual SQL migration is required. Keeping legacy metadata avoids breaking old workers' queries and permits rollback with the same API key and legacy key version. Back up the database before upgrading and stop all old instances before rotating the key. After a key change, the legacy metadata still describes the old key: rollback requires restoring the old configuration or following the old version's rotation procedure, which invalidates OAuth state. Only remove the legacy table manually once all old instances are retired and a rollback is no longer needed; it can still contain the previous key's verifier.

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 database capacity with the total number of MCP processes 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 127.0.0.1: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.

Recorded demo gif

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:

• python -m pytest -q (see Contributing for the full CI coverage gate)
• ruff check .
• mypy src --ignore-missing-imports
• python -m pip_audit -r requirements/runtime.lock --require-hashes --disable-pip --strict
• 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

See Contributing for environment setup, test prerequisites, and pull request guidance.

python -m pytest -q
ruff check .
mypy src --ignore-missing-imports
python -m pip_audit -r requirements/runtime.lock --require-hashes --disable-pip --strict
python -m build

CI also runs PostgreSQL-backed tests and enforces full runtime statement coverage and full branch coverage for critical modules. See Contributing for the exact coverage commands and Dependency updates for the reviewed runtime lock workflow.

Community

• Contributing
• Code of Conduct
• Accessibility
• Security Policy
• Report an issue
• Discussions

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.