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