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:
MCPfor Claude Desktop, Cursor, VS Code, Open WebUI, Codex, and other MCP-capable agentsOpenAPIfor 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.hostproxmox.portauth.userauth.token_nameauth.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"]
}
}
No comments yet.