Unofficial-Proxmox-MCP
Enables conversational management of a Proxmox VE cluster: inspecting nodes, storage, VMs, and LXC containers; provisioning and cloning systems; controlling lifecycle actions; managing snapshots, disks, Cloud-Init, backups, firewall rules, guest networking, and guest command execution; evaluating placement; and exporting Terraform configurations, with built-in confirmation and self-protection safeguards.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Unofficial-Proxmox-MCP list all VMs and containers on node pve1"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Unofficial-Proxmox-MCP π
Production-Grade, Drop-In Model Context Protocol (MCP) Server for Proxmox VE
Unofficial-Proxmox-MCP bridges AI assistants (Antigravity, Claude Desktop, Cursor, Hermes Agent, Open-WebUI, LibreChat) directly with your Proxmox Virtual Environment (PVE) cluster via the official Model Context Protocol.
Manage your virtualization infrastructure conversationally: inspect nodes, provision VMs and LXC containers, resize disks, manage snapshots, configure Cloud-Init, trigger vzdump backups, manage firewall rules, evaluate node placement, query guest IPs, and run guest commandsβwith mandatory two-step confirmation guardrails and container self-protection.
β‘ Deployment Modes: Where Should You Run It?
"Are we using Docker locally, running it directly on the system, or hosting it inside an LXC on Proxmox?"
You have complete flexibility:
βββββββββββββββββββββββββββββββββββ
β AI Assistants & IDEs β
β (Claude, Antigravity, Cursor) β
βββββββββββββββββ¬ββββββββββββββββββ
β
βββββββββΌββββββββββββββββββββββββββ
βΌ βΌ βΌ
[Mode 1] [Mode 2] [Mode 3]
Local Venv Local Docker Proxmox Host LXC
(stdio) (SSE on :8000) (SSE Co-Pilot on :8000)
β β β
βββββββββ΄ββββββββββββ¬ββββββββββββββ
βΌ HTTPS (:8006)
βββββββββββββββββββββββββββββββββ
β Proxmox VE Cluster Node β
β (QEMU VMs, LXC Containers) β
βββββββββββββββββββββββββββββββββDeployment Mode | Transport | Pros | Cons | Ideal For |
Mode 1: Local System (.venv) |
| Zero hypervisor footprint; fastest IPC response; direct Claude/Antigravity integration. | Requires Python on local machine. | Solo developers, daily driver workstations. |
Mode 2: Local / LAN Docker |
| Clean isolation; no Python dependency on host; one-command lifecycle. | Requires Docker running. | Homelab servers, microservices. |
Mode 3: Proxmox Host LXC |
| 24/7 dedicated hypervisor co-pilot; shared across team; auto-self-protection. | Consumes ~1GB RAM on Proxmox. | Multi-agent clusters, team labs. |
Related MCP server: Proxmox MCP Server
π‘οΈ Enterprise Security & Self-Protection Architecture
1. LXC Container Self-Protection
When deployed inside an LXC container on Proxmox (Mode 3), the server automatically detects its own host VMID (via /etc/pve-self-vmid or PVE_SELF_VMID):
It permanently binds its own ID into
protected_vmids.Any command instructing an agent to
stop,shutdown,reset, ordestroythe container running the MCP server is hard-blocked:PermissionError: Self-Protection Block: Cannot destroy VMID 299 because it is the host container running this MCP server.
2. Mandatory Two-Step Confirmation Gates
AI models cannot accidentally wipe your fleet:
System Deletion (
pve_destroy_system): Calling the tool without confirmation safely aborts and returns:{ "status": "confirmation_required", "action": "destroy_system", "vmid": 300, "message": "DESTRUCTION BLOCKED: Deletion requires explicit user confirmation...", "required_params": { "confirm_vmid": 300, "confirmation_phrase": "CONFIRM_DELETE_300" } }The agent must ask the human operator for confirmation. Only re-invoking with
confirm_vmid=300ANDconfirmation_phrase="CONFIRM_DELETE_300"permits deletion.Snapshot Deletion (
pve_delete_snapshot): Requiresconfirmation_phrase="CONFIRM_DELETE_SNAPSHOT_<snapname>".Immune Blacklist (
PVE_PROTECTED_VMIDS): Nodes listed here (e.g. your router, primary storage, domain controllers) can never be destroyed via MCP.
3. Dedicated Least-Privilege Account Creation
The installer provides an interactive wizard to create an isolated service account (mcp-bot@pve) with a scoped role (PVEMCP) instead of using root@pam.
π Comprehensive MCP Tool Suite (19 Drop-In Tools)
1. Fleet Discovery & Telemetry
pve_list_nodes(): Overview of cluster nodes, online status, CPU %, memory allocation, and uptime.pve_get_node_status(node): Deep telemetry (PVE version, Linux kernel, CPU model/sockets/cores, load averages, memory/swap breakdown).pve_list_storage_pools(node): Storage pools (ZFS, LVM, Directory, NFS) with content types (iso, vztmpl, backup, images) and free/used GB.pve_list_systems(node, type_filter, status_filter): Filtered VM and container fleet listing.pve_get_system(vmid, node): Full configuration and live telemetry for a specific instance.pve_get_guest_network(vmid, node): Live IP addresses (IPv4 & IPv6) and MACs via QEMU Guest Agent or LXC network stack.pve_exec_guest_command(vmid, command, node, timeout): Executes a non-interactive shell command inside a QEMU VM via QEMU Guest Agent and returns exit code, stdout, and stderr.
2. Lifecycle & Snapshots
pve_lifecycle(vmid, action, node): Executes state transitions:start,stop,shutdown,reboot,reset,suspend,resumewith automaticUPIDtask polling.pve_create_snapshot(vmid, snapname, description, vmstate, node): Captures instantaneous VM/LXC state (including live RAM).pve_list_snapshots(vmid, node): Snapshot hierarchy and trees.pve_rollback_snapshot(vmid, snapname, start_after, node): Restores system to a prior snapshot.pve_delete_snapshot(vmid, snapname, confirmation_phrase, node): Deletes snapshot and merges delta storage (requires confirmation phrase).
3. Configuration & Provisioning
pve_edit_system(vmid, cores, memory_mb, description, tags, onboot, node): Modifies CPU cores, RAM limits, notes, tags, and auto-start.pve_resize_disk(vmid, disk, add_gb, node): Incremental storage expansion (scsi0,rootfs, etc.).pve_set_cloudinit(vmid, ciuser, cipassword, sshkeys, ipconfig0, nameserver, searchdomain, node): Configures Cloud-Init drive on a VM.pve_clone_system(source_vmid, new_vmid, new_name, full_clone, target_storage, target_node): Clones templates/instances (full or linked clone).pve_create_lxc(vmid, hostname, ostemplate, cores, memory_mb, disk_gb, storage, password, ssh_public_key, unprivileged, node): Provisions new container from template.pve_create_vm(vmid, name, cores, memory_mb, disk_gb, storage, iso_image, node): Provisions new QEMU virtual machine.pve_destroy_system(vmid, confirm_vmid, confirmation_phrase, purge_data, node): Safely purges an instance (requires confirmation phrase + blacklist clearance).
4. Advanced Management & IaC
pve_trigger_backup(vmid, storage, mode, compression, node): Triggers immediatevzdumpbackup.pve_list_backups(storage, node): Lists backup archives and sizes in a storage pool.pve_get_firewall(vmid, node): Inspects active firewall rules and security options.pve_set_firewall_rule(vmid, action, rule_type, proto, dport, comment, enable, node): Adds or updates a firewall rule.pve_recommend_placement(required_cores, required_mem_mb, required_disk_gb): Analyzes cluster CPU and memory congestion to recommend the optimal node.pve_get_vnc_ticket(vmid, node): Generates time-limited NoVNC console URL and tickets.pve_export_terraform(vmid, node): Generates ready-to-run Terraform / OpenTofu.tfconfigurations.
π Interactive Installation
Linux / macOS:
git clone https://github.com/your-username/Unofficial-Proxmox-MCP.git
cd Unofficial-Proxmox-MCP
chmod +x install.sh
./install.shPrompts for deployment mode (Local, Docker, or Host LXC), offers to auto-generate the dedicated mcp-bot@pve user, and verifies connectivity.
Windows (PowerShell):
git clone https://github.com/your-username/Unofficial-Proxmox-MCP.git
cd Unofficial-Proxmox-MCP
.\install.ps1 -Target Local
# or .\install.ps1 -Target DockerProxmox VE Host Turnkey LXC:
Run directly on your Proxmox hypervisor shell:
curl -fsSL https://raw.githubusercontent.com/your-username/Unofficial-Proxmox-MCP/main/pve-lxc-deploy.sh | bashπ€ Drop-In AI Configuration
Claude Desktop (claude_desktop_config.json)
{
"mcpServers": {
"proxmox": {
"command": "uvx",
"args": ["unofficial-proxmox-mcp"],
"env": {
"PVE_HOST": "192.168.1.100",
"PVE_USER": "mcp-bot@pve!mcp-token",
"PVE_TOKEN_SECRET": "your-token-secret-uuid",
"PVE_VERIFY_SSL": "false",
"PVE_PROTECTED_VMIDS": "100,101,200"
}
}
}
}Antigravity / Cursor / LibreChat
{
"mcpServers": {
"proxmox": {
"command": "python",
"args": ["-m", "unofficial_proxmox_mcp"],
"env": {
"PVE_HOST": "192.168.1.100",
"PVE_USER": "mcp-bot@pve!mcp-token",
"PVE_TOKEN_SECRET": "your-token-secret-uuid",
"PVE_VERIFY_SSL": "false"
}
}
}
}π§ͺ Testing & Verification
pytest tests -v
# 19 passed in 1.25sπ License
Released under the MIT License.
Available Tools
26 toolspve_clone_systemB
Clone a new VM or LXC container from an existing template or system.
Args: source_vmid: Source template or instance VMID. new_vmid: Unique ID for the newly created instance (e.g. 301). new_name: Hostname or display name for the new system. full_clone: If True, makes an independent full clone. If False, creates a linked clone. target_storage: Storage pool name (e.g. 'local-lvm', 'fast-tier'). Optional. target_node: Target node name. Optional.
Inputs: new_name (required), new_vmid (required), source_vmid (required), full_clone, +2 more. Returns: result
pve_create_lxcB
Create a new LXC container from an OS template tarball.
Args: vmid: Unique Container ID (e.g. 255). hostname: Hostname for the container. ostemplate: Storage template path (e.g. 'local:vztmpl/ubuntu-22.04-standard_22.04-1_amd64.tar.zst'). cores: Number of assigned CPU cores. memory_mb: Memory in megabytes. disk_gb: Root filesystem disk size in gigabytes. storage: Target storage pool (e.g. 'local-lvm' or 'fast-tier'). password: Root user password. ssh_public_key: Optional SSH public key to inject into /root/.ssh/authorized_keys. net0: Network interface configuration string. unprivileged: If True, provisions container in an unprivileged user namespace (recommended). node: Target node name.
Inputs: vmid (required), hostname (required), ostemplate (required), net0, +8 more. Returns: result
pve_create_snapshotB
Take a snapshot of a VM or LXC container.
Args: vmid: Target VM or Container ID. snapname: Name for the snapshot (alphanumeric and dashes/underscores, e.g. 'pre-upgrade-v1'). description: Informative description or changelog for the snapshot. vmstate: For QEMU VMs only. If True, saves running RAM state (live snapshot). node: Optional node name.
Inputs: vmid (required), snapname (required), node, vmstate, +1 more. Returns: result
pve_create_vmB
Create a new QEMU virtual machine.
Args: vmid: Unique Virtual Machine ID (e.g. 150). name: Name / hostname of the virtual machine. cores: Number of virtual CPU cores. memory_mb: Memory in megabytes. disk_gb: Boot disk size in gigabytes. storage: Target storage pool (e.g. 'local-lvm', 'fast-tier'). iso_image: Optional ISO image path (e.g. 'local:iso/ubuntu-24.04-live-server-amd64.iso'). net0: Network interface configuration string. node: Target node name.
Inputs: name (required), vmid (required), net0, node, +5 more. Returns: result
pve_delete_snapshotA
Delete a snapshot from a VM or LXC container.
SAFETY REQUIREMENT: Deleting a snapshot merges or purges historical states. If confirmation_phrase is not provided, this tool will safely block and ask you to confirm with confirmation_phrase='CONFIRM_DELETE_SNAPSHOT_'.
Args: vmid: Target VM or Container ID. snapname: Snapshot identifier to delete. confirmation_phrase: Explicit confirmation phrase (e.g. 'CONFIRM_DELETE_SNAPSHOT_pre-upgrade'). node: Optional node name.
Inputs: vmid (required), snapname (required), node, confirmation_phrase. Returns: result
pve_destroy_systemA
Safely delete and remove a virtual machine or LXC container.
MANDATORY CONFIRMATION SAFETY GATES:
If confirm_vmid != vmid OR confirmation_phrase != 'CONFIRM_DELETE_', this tool will SAFELY REFUSE destruction and return a confirmation request. You must ask the user explicitly to confirm deletion before calling with the matching confirmation phrase.
Self-Protection: Cannot delete the container hosting this MCP server.
The target vmid MUST NOT be included in PVE_PROTECTED_VMIDS blacklist.
The instance will be cleanly stopped prior to deletion.
Args: vmid: Target ID of the VM or container to destroy. confirm_vmid: Must equal vmid as an explicit confirmation gate. confirmation_phrase: Must equal 'CONFIRM_DELETE_' (e.g. 'CONFIRM_DELETE_300'). purge_data: Whether to purge and release all associated virtual disks and backup files. node: Optional node name.
Inputs: vmid (required), node, purge_data, confirm_vmid, +1 more. Returns: result
pve_edit_systemB
Edit configuration parameters of an existing VM or container (CPU cores, RAM, notes, tags, onboot).
Args: vmid: Target VM or Container ID. cores: Number of virtual CPU cores to assign. memory_mb: Allocated RAM in megabytes (e.g. 4096 for 4GB). description: Notes / documentation markdown string. tags: Semicolon or comma-separated tags (e.g. 'web;production;docker'). onboot: Whether the system automatically starts on Proxmox node boot. node: Optional node name.
Inputs: vmid (required), node, tags, cores, +3 more. Returns: result
pve_exec_guest_commandA
Execute a non-interactive shell command inside a QEMU VM via the QEMU Guest Agent. Returns exit code, stdout, and stderr.
Args: vmid: Target QEMU Virtual Machine ID. command: Shell command string to execute (e.g. 'ip a', 'uptime', 'docker ps'). node: Optional node name. timeout: Execution timeout in seconds (default: 30).
Inputs: vmid (required), command (required), node, timeout. Returns: result
pve_export_terraformA
Export the complete live specification of a VM or container into a ready-to-run Terraform / OpenTofu (.tf) block.
Args: vmid: Target VM or LXC Container ID. node: Optional node name.
Inputs: vmid (required), node. Returns: result
pve_get_firewallC
Inspect the firewall rules and security options active on a VM or container.
Args: vmid: Target VM or LXC Container ID. node: Optional node name.
Inputs: vmid (required), node. Returns: result
pve_get_guest_networkA
Retrieve live guest IP addresses (IPv4 & IPv6), MAC addresses, and network interfaces. Uses QEMU Guest Agent for VMs, or container interface discovery for LXC.
Args: vmid: Target VM or LXC Container ID. node: Optional node name.
Inputs: vmid (required), node. Returns: result
pve_get_node_statusA
Get deep telemetry for a Proxmox node: PVE version, kernel version, CPU sockets/cores/model, load averages, and memory/swap utilization in MB.
Args: node: Target node name (e.g. 'pve'). Defaults to cluster default node if empty.
Inputs: node. Returns: result
pve_get_systemA
Get detailed hardware configuration, network adapters, memory, disk layouts, and live status for a VM or LXC container.
Args: vmid: Target VM or LXC Container ID (e.g. 101 or 204). node: Optional node name. If omitted, automatically locates the system across cluster nodes.
Inputs: vmid (required), node. Returns: result
pve_get_vnc_ticketA
Generate a time-limited NoVNC console ticket and URL for browser-based out-of-band management.
Args: vmid: Target VM or LXC Container ID. node: Optional node name.
Inputs: vmid (required), node. Returns: result
pve_lifecycleB
Perform a lifecycle state transition on a VM or container.
Args: vmid: Target VM or Container ID. action: One of: 'start', 'stop', 'shutdown', 'reboot', 'reset', 'suspend', 'resume'. node: Optional node name. Automatically discovers node if omitted.
Inputs: vmid (required), action (required), node. Returns: result
pve_list_backupsB
List available backup archives stored in a designated storage pool.
Args: storage: Storage pool identifier (e.g. 'local', 'vault-backups'). node: Optional node name.
Inputs: node, storage. Returns: result
pve_list_nodesB
List all cluster nodes, their online status, CPU usage %, memory allocation, and uptime. Returns JSON formatted overview.
Inputs: no named parameters. Returns: result
pve_list_snapshotsB
List all existing snapshots and hierarchy for a VM or LXC container.
Args: vmid: Target VM or Container ID. node: Optional node name.
Inputs: vmid (required), node. Returns: result
pve_list_storage_poolsA
List all configured storage pools (ZFS, LVM-Thin, Directory, NFS, Ceph) on a node or cluster, including enabled content types (iso, vztmpl, images, backup), total space, used, and free GB.
Args: node: Target node name. Defaults to cluster default node if empty.
Inputs: node. Returns: result
pve_list_systemsA
List virtual machines and LXC containers in the cluster.
Args: node: Filter by specific node name (e.g. 'pve') or 'all' across cluster. type_filter: 'all', 'qemu' (VMs only), or 'lxc' (Containers only). status_filter: 'all', 'running', or 'stopped'.
Inputs: node, type_filter, status_filter. Returns: result
pve_recommend_placementA
Analyze cluster resource congestion and recommend the optimal node for placing new workloads.
Args: required_cores: Number of virtual CPU cores needed. required_mem_mb: RAM in megabytes required. required_disk_gb: Storage in gigabytes required.
Inputs: required_cores, required_mem_mb, required_disk_gb. Returns: result
pve_resize_diskB
Incrementally expand the storage capacity of a virtual disk.
Args: vmid: Target VM or Container ID. disk: Disk device identifier (e.g. 'scsi0', 'virtio0', or 'rootfs'). add_gb: Size in gigabytes to expand by (e.g. 10 adds 10GB). node: Optional node name.
Inputs: disk (required), vmid (required), add_gb (required), node. Returns: result
pve_rollback_snapshotB
Revert a VM or LXC container to a previous snapshot state.
Args: vmid: Target VM or Container ID. snapname: Name of the snapshot to restore. start_after: If True, automatically powers the system on after rollback completes. node: Optional node name.
Inputs: vmid (required), snapname (required), node, start_after. Returns: result
pve_set_cloudinitB
Configure Cloud-Init parameters on a QEMU virtual machine.
Args: vmid: Target VM ID. ciuser: Default cloud-init username (e.g. 'ubuntu' or 'debian'). cipassword: User password. sshkeys: URL-encoded or raw OpenSSH public key string. ipconfig0: IP addressing config (e.g. 'ip=dhcp' or 'ip=192.168.1.50/24,gw=192.168.1.1'). nameserver: DNS nameserver IP. searchdomain: DNS search domain. node: Optional node name.
Inputs: vmid (required), node, ciuser, sshkeys, +4 more. Returns: result
pve_set_firewall_ruleB
Add or modify a firewall rule on a VM or container.
Args: vmid: Target VM or LXC Container ID. action: 'ACCEPT', 'DROP', or 'REJECT'. rule_type: 'in' (inbound) or 'out' (outbound). proto: Protocol: 'tcp', 'udp', 'icmp', etc. dport: Destination port or port range (e.g. '80', '443', '8000:8050'). comment: Brief description of the firewall rule. enable: Whether the rule is actively enabled. node: Optional node name.
Inputs: vmid (required), action (required), node, dport, +4 more. Returns: result
pve_trigger_backupB
Execute an immediate vzdump backup of a VM or container to a target storage pool.
Args: vmid: Target VM or LXC Container ID. storage: Target backup storage pool (e.g. 'local', 'pbs-backup'). mode: Backup mode: 'snapshot' (live, zero downtime), 'suspend', or 'stop'. compression: Compression algorithm: 'zstd', 'gzip', or 'none'. node: Optional node name.
Inputs: vmid (required), mode, node, storage, +1 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 26 tools
Most tools are clearly separated by resource and action, such as list_nodes vs list_systems and create_vm vs clone_system. Minor ambiguity exists between pve_get_system and pve_get_guest_network because both can return network-related information, and pve_export_terraform partially overlaps with configuration retrieval.
All tools use the pve_ snake_case prefix and nearly all follow a verb_noun pattern. The main exception is pve_lifecycle, which is noun-style rather than verb-style, but the naming remains highly predictable overall.
With 26 tools, the set is above the typical 3β15 range, but the broad Proxmox domain includes many distinct operations. Each tool generally earns its place, though the surface is slightly heavy and some specialized tools could potentially be consolidated.
The core VM/container lifecycle is well covered, including create, clone, edit, resize, lifecycle actions, destroy, snapshots, and Terraform export. However, notable gaps remain: backup restore/delete, firewall rule deletion, migration, task tracking, and node/storage network administration are missing, creating several dead ends.
Maintenance
Related MCP Connectors
Manage Vozora VPS servers, SSH keys, firewalls, DNS and usage from an AI agent.
Manage Rackspace Spot Kubernetes Cloudspaces, node pools, and VMs from your AI assistant.
Manage VeriTeknik servers, DNS, backups and support tickets from your AI assistant.
Provides capabilities that let LLM agents perform a range of infrastructure management tasks.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage Proxmox VE infrastructure, including VMs, containers, storage, and cluster operations via natural language.MIT
- AlicenseCqualityDmaintenanceEnables management of Proxmox VE environments, including VMs, containers, storage, and cluster operations through natural language.7649 npmMIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to monitor and manage Proxmox VE infrastructure, including nodes, VMs, containers, storage, backups, and networking, via natural language.1MIT
- AlicenseBqualityDmaintenanceEnables AI assistants to manage Proxmox VE infrastructure, including VMs, containers, storage, network, high availability, replication, SDN, and node administration.10018 npmMIT