ProxmoxMCP Plus

Use MCP and OpenAPI to safely control Proxmox VE VMs, LXCs, backups, and snapshots from LLMs and AI agents.

LLM Mart 4 views 63k listing impressions

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

Architecture: MCP and OpenAPI entry points, guarded target-aware tools, Proxmox VE, and persistent jobs

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"]
  }
}

From the project's README.

Comments (0)

Sign in to join the conversation.

No comments yet.