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

What Makes It Different

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.
• 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.
• 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.

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

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"
  }
}

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:

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 \
  -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

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_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.

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.

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.