ProxmoxMCP-Plus

Control Proxmox VE from LLMs, AI agents, MCP clients, and OpenAPI tooling with one safer interface for VMs, LXCs, backups, snapshots, ISOs, container commands, and persistent long-running jobs.

Quick Start | Demo | Capabilities | Scenarios | Docs | Wiki

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

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

Create it from the example first:

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.

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

OpenAPI mode remains 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

Native MCP Streamable HTTP mode is available from the same image:

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 that support Streamable HTTP at http://<docker-host>:8000/mcp.

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

export PROXMOX_API_KEY="${PROXMOX_API_KEY:-$(openssl rand -hex 32)}"
docker compose up -d
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.

4. Run the native MCP Streamable HTTP surface

docker compose --profile mcp-http up -d proxmox-mcp-http

Connect a Streamable HTTP MCP client to:

http://localhost:8000/mcp

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

5. Point a stdio 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 authenticated 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:

Capability Area	Availability
VM create / start / stop / delete	Available
VM snapshot create / rollback / delete	Available
Backup create / restore	Available
ISO download / delete	Available
LXC create / start / stop / delete	Available
Container SSH-backed command execution	Available
Container authorized_keys update	Available
Persistent job store for long tasks	Available
MCP job control tools (list_jobs, get_job, poll_job, cancel_job, retry_job)	Available
OpenAPI /jobs endpoints with explicit status codes	Available
Local OpenAPI /livez, /readyz, /health, and schema	Available
Docker native MCP Streamable HTTP at /mcp	Available
Docker image build and /livez	Available

Validation and contract entry points in this repository:

• pytest -q --cov=proxmox_mcp --cov-report=term-missing --cov-fail-under=60
• 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.

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:

Path	Method	Purpose	Success Codes
/jobs	GET	list persisted jobs	200
/jobs/{job_id}	GET	fetch one job, optional refresh=true	200
/jobs/{job_id}/poll	POST	refresh status from Proxmox	200
/jobs/{job_id}/cancel	POST	request cancellation	202
/jobs/{job_id}/retry	POST	replay a stored retry recipe	202

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

Capability	Official Proxmox API	One-off scripts	ProxmoxMCP-Plus
MCP for LLM and AI agent workflows	No	No	Yes
OpenAPI surface for standard HTTP tooling	No	Usually no	Yes
VM and LXC operations in one interface	Low-level only	Depends	Yes
Snapshot, backup, and restore workflows	Low-level only	Depends	Yes
Persistent async job tracking and retry	No	Rare	Yes
Container command execution with policy controls	No	Custom only	Yes
Docker distribution path	No	Rare	Yes
Repository-level live-environment verification	N/A	Rare	Yes

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.

If you need to...	Start here
Understand the project and deployment flow	Wiki Home
Configure and run against a Proxmox environment	Operator Guide
Connect Claude Desktop or Open WebUI	Integrations Guide
Install from MCP-aware IDEs and agents	Agent Installation
Enable LXC command execution over SSH	Container Command Execution
Review security and command policy	Security Guide
Inspect tool parameters, prerequisites, and behavior	API & Tool Reference
Debug startup, auth, or health issues	Troubleshooting
Work on the codebase or release it	Developer Guide
Review release and upgrade notes	Release & Upgrade Notes

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=60
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