RekklesNA/ProxmoxMCP-Plus

Big picture: ProxmoxMCP-Plus is a control layer that lets AI assistants (and ordinary HTTP tools) operate a Proxmox VE virtualization server — creating VMs, managing Linux containers (LXCs), taking snapshots, running backups, pulling ISOs — through one uniform, security-conscious interface. Instead of hand-writing raw Proxmox API calls and shell scripts, operators set up this server once and point their tools at it.

The problem it solves

Proxmox VE is the underlying system that hosts virtual machines and containers. Normally, to automate tasks on it you'd stitch together raw API calls, ad-hoc scripts, and custom job-polling loops. This project replaces that patchwork with a single tool that speaks two industry-standard languages:

• MCP (Model Context Protocol): how AI agents like Claude Desktop, Cursor, VS Code, or Open WebUI talk to external tools. This is the "AI client" path.
• OpenAPI (REST/HTTP): how traditional dashboards, internal scripts, and no-code automation platforms call services. This is the "standard HTTP" path.

Both paths feed into the same workflows, so you can use one or the other (or both) without learning two different systems.

What it actually does

From the README, the operational surface includes:

• VM and LXC lifecycle actions — start, stop, create, delete virtual machines and containers
• Snapshots — create, roll back, delete
• Backup and restore workflows
• ISO download and cleanup — grabbing installation images and removing old ones
• Node, storage, and cluster inspection — checking the health and status of the hypervisor and its environment
• SSH-backed container commands — running commands inside a container with guardrails (optional; requires SSH config)
• Opt-in guarded node SSH commands — running commands on the Proxmox host itself, also guarded and opt-in
• Persistent job tracking — long-running Proxmox tasks get stable job IDs (job_id), track the Proxmox UPID, and support polling, retry, cancel, and audit history

How you run it

The README gives three main runtime paths:

1. MCP stdio from PyPI — the classic way for local AI clients (Claude Desktop, Cursor, VS Code). Launch with uvx proxmox-mcp-plus or pip install proxmox-mcp-plus.

2. Native MCP HTTP via Docker — for remote MCP clients that support "Streamable HTTP" transport. Starts on port 8000 at /mcp, requires an API key via MCP_API_KEY.

3. OpenAPI bridge via Docker — the default Docker mode, serving REST endpoints on port 8811, secured by PROXMOX_API_KEY. Health endpoint at /livez, spec at /openapi.json.

Before any of those, you create a PProxmox API token, copy proxmox-config/config.example.json to proxmox-config/config.json, and fill in host, port, user, and token details. (Optionally add ssh and jobs sections.)

Safety features

The README emphasizes a "security-conscious" design:

• API tokens for Proxmox with least-privilege permissions
• Bearer token auth for the OpenAPI bridge
• Command policy — rules governing what container/host commands are allowed
• Approval tokens — ops can require explicit human approval for certain actions
• TLS validation — verifies SSL certificates by default
• MCP HTTP Host/Origin controls — DNS-rebinding protection and allow-listed origins
• Tool exposure filtering — an optional allowlist/denylist to limit which tool schemas the server sends to clients; an empty list disables everything, unknown names fail startup, and only exact lowercase names work

Code Mode (opt-in)

By default the server exposes the full catalog of tools. If you set mcp.code_mode: true (or MCP_CODE_MODE=true), it flips to three tools instead:

• proxmox_code_search — discover what's available
• proxmox_code_get_schema — get argument schemas
• proxmox_code_execute — run a scripted expression against the domain tools

Code execution runs in an isolated sandbox (no filesystem or network access except registered tool calls) with hard limits: 64,000 source characters, 100 MB memory, 25 tool calls, 16 KB final JSON, two concurrent executions, and a 30-second budget. Cancelling or failing a script does not roll back tool side effects — so you shouldn't auto-retry a failed mutation. Optional worker-pool reuse is available (mcp.code_mode_pool_reuse).

OAuth browser gate (optional, native MCP HTTP)

A more sophisticated auth flow for remote MCP clients: instead of sending the raw API key, users go through an OAuth authorization-code flow with PKCE (a secure login standard), where the only credential a human needs is MCP_API_KEY. The browser visits a consent page, reviews what the client wants, and enters the key. The OAuth state is stored in PostgreSQL (not a local file), so multiple server instances can share state safely. The server relies on the MCP Python SDK for the protocol endpoints and adds the consent page plus the API-key policy.

Key requirements when toggling MCP_OAUTH_ENABLED=true: MCP_OAUTH_ISSUER (public HTTPS origin), MCP_OAUTH_DATABASE_URL (PostgreSQL DSN), and MCP_API_KEY. With OAuth on, a raw Authorization: Bearer <key> request is rejected — only issued OAuth tokens work.

What makes it different (from the project's own table)

Priority	Approach
Dual access paths	Native MCP + OpenAPI on the same workflows
Proxmox-oriented	Day-2 operations beyond basics: snapshots, backups, ISOs, storage, clusters
Long-running work	Stable job IDs, UPID tracking, polling, retry, cancel, audit trail
Safer execution	Tokens, command policy, approvals, TLS validation, Host/Origin controls
Real validation	Unit, integration, Docker/OpenAPI, and live Proxmox tests (documented in the repo)

Bottom line

If you operate a Proxmox VE cluster and want AI agents or HTTP automation to safely manage it, this project gives you one installable bridge with two interfaces, a strong security posture, and solid job-tracking for the asynchronous tasks Proxmox is known for. It's configurable via a JSON file and environment variables, runs from PyPI or Docker, and includes gentle guardrails (allowlists, approvals, sandboxes) for when you let autonomous agents touch your infrastructure.