ProxmoxMCP-Plus

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

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

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

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:

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
Local OpenAPI /health and schema	Available
Docker image build and /health	Available

Validation and contract entry points in this repository:

• pytest -q
• tests/integration/test_real_contract.py
• test_scripts/run_real_e2e.py

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
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 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	llms-installation.md
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
• test_scripts/run_real_e2e.py: live Proxmox and Docker/OpenAPI path
• tests/: unit and integration coverage
• 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 test_scripts/run_real_e2e.py
python -m build

License

MIT