ProxmoxMCP-Plus

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:

- MCPfor Claude Desktop, Cursor, VS Code, Open WebUI, Codex, and other MCP-capable agents
- OpenAPIfor HTTP automation, dashboards, internal tools, and no-code workflows

- 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

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 editproxmox-config/config.jsonwith your environment. At minimum, it needs:

- proxmox.host
- proxmox.port
- auth.user
- auth.token_name
- auth.token_value

Add ansshsection as well if you want container command execution. Add ajobssection if you want job state persisted somewhere other than the default local SQLite file.

For real live verification, use a separateproxmox-config/config.live.jsoncreated fromproxmox-config/config.live.example.json. Do not point live e2e at a placeholder or local-onlyconfig.jsonunless you intentionally run a local API tunnel there.

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

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:

export MCP_API_KEY="$(openssl rand -hex 32)" 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_API_KEY="$MCP_API_KEY" \ -v "$(pwd)/proxmox-config/config.json:/app/proxmox-config/config.json:ro" \ ghcr.io/rekklesna/proxmoxmcp-plus:latest

SendAuthorization: Bearer <MCP_API_KEY>with every MCP HTTP request.MCP_API_KEYis deliberately separate from the OpenAPI-onlyPROXMOX_API_KEY, so the two surfaces can be rotated independently. IfMCP_API_KEYis unset, Streamable HTTP remains unauthenticated for backward compatibility and logs a security warning at startup.

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_API_KEY="$MCP_API_KEY" \ -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

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, setPROXMOX_ALLOW_NO_AUTH=true.

This demo is a direct terminal recording ofqwen/qwen3.6-plusdriving 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/healthsurface.

Start with read-only discovery, then move to mutating tools only after the target node, storage, VMID, and permissions are clear.

ProxmoxMCP-Plus is an access layer, not a replacement for Proxmox RBAC, network controls, or client-side MCP approval prompts.

The project gives operators several control points:

- Proxmox API tokens decide what the backend can do.
- PROXMOX_API_KEYprotects the OpenAPI bridge by default.
- MCP_API_KEYoptionally protects the native Streamable HTTP/mcpendpoint with Bearer authentication.
- TLS verification is enforced unless development mode is explicitly enabled.
- command_policycontrols command execution and high-risk operations.
- approval_tokencan gate command execution and high-risk mutating actions.
- MCP Streamable HTTP deployments can use DNS rebinding protection plus Host and Origin allowlists.
- Logs are designed to avoid exposing command and credential material.

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.

Validation and contract entry points in this repository:

- pytest -q --cov=proxmox_mcp --cov-report=term-missing --cov-fail-under=75
- 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.pynow prefersproxmox-config/config.live.jsonorPROXMOX_MCP_E2E_CONFIG. This avoids accidentally running live checks against a machine-specific defaultconfig.json.

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 stableJob 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 ProxmoxUPID
- job_id: the stable server-side job record

- current status and progress
- retry count and priorUPIDs
- latest result payload or failure reason
- audit history for create, poll, retry, and cancel actions

By default the job store persists toproxmox-jobs.sqlite3, so restart does not lose in-flight or completed job metadata.

- list_jobs
- get_job
- poll_job
- cancel_job
- retry_job

When the OpenAPI proxy is enabled and a localJobStoreis available, these routes are exposed directly:

- 404: unknownjob_id
- 409: the job exists but that operation is not valid now
- 503: the OpenAPI proxy was started without a localJobStore

tests/scripts/run_real_e2e.pynow prefersproxmox-config/config.live.jsonorPROXMOX_MCP_E2E_CONFIG. This avoids accidentally running live checks against a machine-specific defaultconfig.json.

These are written for both human operators and LLM-driven usage.

The README is intentionally optimized for fast GitHub comprehension. Longer operational docs live indocs/wiki/and can also be published to the GitHub Wiki.

- 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

pytest -q --cov=proxmox_mcp --cov-report=term-missing --cov-fail-under=75 ruff check . mypy src --ignore-missing-imports pip-audit -r requirements.txt python -m build

Paramiko 5.0.0 or newer is required sopip-auditcan run without aCVE-2026-44405exception.

Get prescriptive CDK advice, explain CDK Nag rules, check suppressions, generate Bedrock Agent schemas, and discover AWS Solutions Constructs patterns.

Core AWS MCP server providing prompt understanding and server management capabilities.

Manage and interact with Microsoft Azure services.

Official Model Context Protocol (MCP) server for esa.io - STDIO transport version.

An MCP Server that connects to Gemini Cloud Assist APIs, enabling you to manage and troubleshoot your Google Cloud environment using natural language.

The IBM Instana MCP server enables seamless interaction with the IBM Instana observability platform, allowing you to access real-time observability data directly within your development workflow.

Official Metabase MCP server for searching data, building queries on the semantic layer, and visualizing results through MCP clients.

Query and interact with kubernetes environments monitored by Metoro

Exposes cloud provider control and data planes to agents as self-describing, queryable and mutable data sources using SQL, minimising tool surface and token usage.