by RekklesNA
Use MCP and OpenAPI to safely control Proxmox VE VMs, LXCs, backups, and snapshots from LLMs and AI agents.
# Add to your Claude Code skills
git clone https://github.com/RekklesNA/ProxmoxMCP-PlusGuides for using ai agents skills like ProxmoxMCP-Plus.
Last scanned: 5/30/2026
{
"issues": [],
"status": "PASSED",
"scannedAt": "2026-05-30T15:32:42.718Z",
"npmAuditRan": true,
"pipAuditRan": false
}No comments yet. Be the first to share your thoughts!
30 days in the Featured rail
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 agentsOpenAPI for HTTP automation, dashboards, internal tools, and no-code workflowsWhat you get:
| Priority | How the project handles it |
| --- | --- |
| Dual access paths | Native MCP for agent workflows and OpenAPI for standard HTTP automation |
| Proxmox-oriented workflows | Day-2 VM, LXC, snapshot, backup, ISO, storage, and cluster operations |
| Long-running operations | Stable job_ids, Proxmox UPID tracking, polling, retry, cancel, and audit history |
| Safer execution | Proxmox API tokens, OpenAPI bearer auth, command policy, approval tokens, TLS validation, and MCP HTTP Host/Origin controls |
| Real validation | Unit, integration, Docker/OpenAPI, and live Proxmox e2e entry points are documented in the repo |
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.hostproxmox.portauth.userauth.token_nameauth.token_valueAdd 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"
}
}
| Path | Best for | Start command | Verify |
| --- | --- | --- | --- |
| MCP stdio from PyPI | Claude Desktop, Cursor, VS Code, Codex, local agents | uvx proxmox-mcp-plus | client lists get_nodes, get_vms, and job tools |
| Native MCP HTTP from Docker | remote MCP clients that support Streamable HTTP | docker compose --profile mcp-http up -d proxmox-mcp-http | connect to http://localhost:8000/mcp |
| OpenAPI bridge from Docker | HTTP clients, dashboards, scripts, no-code tools | docker compose up -d | curl -f http://localhost:8811/livez |
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.
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 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.
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.
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.
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.
