ProxmoxMCP-Plus

Platform Overview

ProxmoxMCP-Plus provides a unified Proxmox VE control surface in two forms:

• MCP for Claude Desktop, Open WebUI, and other LLM or AI agent clients

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

Instead of stitching together raw Proxmox API calls, shell scripts, and custom glue code, the project consolidates core operational workflows in one interface:

• 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: Lodestar MCP Server

Design Priorities

ProxmoxMCP-Plus is designed for the gap between low-level Proxmox primitives and production-facing workflows that need to be usable from both LLM-native clients and standard automation systems.

• Dual-surface architecture: MCP for conversational workflows, OpenAPI for standard automation

• Operator-oriented scope: focused on day-2 tasks, not just raw low-level endpoints

• Safer-by-default execution: auth, command policy, and explicit execution paths

• Observable long-running workflows: stable Job IDs, progress polling, retry, cancel, and audit history

• Operationally grounded: documented workflows are backed by live-environment verification

Quick Start

1. Prepare Proxmox access

Read the official Proxmox docs first if you are setting up a fresh lab:

• Proxmox VE installation guide

• Proxmox VE API guide

• Proxmox VE administration guide

• Linux Container guide

At minimum, proxmox-config/config.json 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.

Minimal job persistence config:

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

2. Choose one runtime path

PyPI

uvx proxmox-mcp-plus

Or install it first:

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

Docker / GHCR

docker run --rm -p 8811:8811 \
  -v "$(pwd)/proxmox-config/config.json:/app/proxmox-config/config.json:ro" \
  ghcr.io/rekklesna/proxmoxmcp-plus:latest

Source

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

3. Run the HTTP/OpenAPI surface

docker compose up -d
curl -f http://localhost:8811/health
curl http://localhost:8811/openapi.json

4. Point an MCP client at the server

Minimal MCP client shape:

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

Client-specific examples for Claude Desktop and Open WebUI are in the 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 HTTP /health surface.

Watch the MP4 version

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

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

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

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

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

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
ruff check .
mypy src tests main.py tests/scripts/run_real_e2e.py
python -m build

License

MIT