ProxmoxMCP-Plus

Operate Proxmox VE from MCP clients, AI agents, and OpenAPI tooling through one security-conscious control plane for VMs, LXCs, snapshots, backups, ISOs, container commands, and persistent long-running jobs.

Quick Start | Client Install | Demo | Tools | Safety | Scenarios | Docs | Wiki

MCP and OpenAPI are alternative entry points into the same workflows and may run in separate processes. Solid arrows show requests and execution; dashed arrows show persisted job and audit state. Approval gates, SSH execution and MCP HTTP OAuth depend on configuration. Select the diagram to view it at full size.

Why 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:

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

What you get:

• 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
• opt-in guarded Proxmox node SSH commands
• persistent job tracking for async Proxmox tasks

What Makes It Different

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

Quick Start

1. Prepare Proxmox Credentials

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

Optional job persistence config:

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

Optional tool exposure filtering can reduce the schemas sent to MCP clients. It is disabled by default, so existing configurations continue to expose every available tool. Configure exactly one mode under mcp:

{
  "mcp": {
    "tool_allowlist": ["get_nodes", "get_vms", "get_containers", "get_storage"]
  }
}

Alternatively, use tool_denylist, or the comma-separated environment variables MCP_TOOL_ALLOWLIST and MCP_TOOL_DENYLIST. Do not configure both modes. Environment selection replaces the file-level filtering mode. An empty allowlist exposes no tools; an empty denylist hides none. Exact lowercase tool names are required, and unknown names fail startup so a typo cannot silently widen access. Restart or reconnect the MCP server after changing the filter.

2. Choose One Runtime Path

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 --profile openapi up -d proxmox-mcp-api	curl -f http://localhost:8811/livez

Docker examples publish host ports on 127.0.0.1 by default; Compose modes are opt-in. Set only the selected mode's key: MCP_API_KEY for native HTTP or PROXMOX_API_KEY for OpenAPI. See Compose deployment and upgrade notes for reverse proxies, tunnels, explicit LAN bindings and container recreation.

MCP stdio with PyPI

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.

Code Mode (opt-in)

Code Mode is disabled by default to preserve the legacy full tool catalog. Enable it with mcp.code_mode: true in the config file or MCP_CODE_MODE=true. When enabled, MCP exposes three tools instead: proxmox_code_search, proxmox_code_get_schema, and proxmox_code_execute. Code execution runs in an isolated sandbox and reaches domain tools through the existing validation, policy, and approval path. Discovery uses the filtered runtime catalog, so it also works in installed wheels. For example:

await call_tool("get_nodes", {"target": "default"})

The final expression is returned as data.result; tool results use MCP JSON content blocks (and structured content where supplied). Use proxmox_code_get_schema for arguments, including target and approval tokens. Scripts have no filesystem or network access except registered tool calls. Limits: 64,000 source characters, 100 MB sandbox memory, 2