ProxmoxMCP-Plus

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.

|

|

|

|

|

|

|

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

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.

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

Send `Authorization: Bearer ` with every MCP HTTP request. `MCP_API_KEY`

is deliberately separate from the OpenAPI-only `PROXMOX_API_KEY`, so the two surfaces

can be rotated independently. If `MCP_API_KEY` is unset, Streamable HTTP remains

unauthenticated for backward compatibility and logs a security warning at startup.

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

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_DNS_REBINDING_PROTECTION=true \
  -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

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` optionally protects the native Streamable HTTP `/mcp` endpoint with Bearer authentication.
• 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 `UPID`s
• 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.

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