proxmox-mcp
The proxmox-mcp server exposes your Proxmox VE cluster to Claude Code, allowing you to monitor, manage, and provision virtual machines and LXC containers via the Proxmox REST API.
Cluster & Node Monitoring
List all nodes and their current status
Get detailed CPU usage, memory, and uptime for a specific node
List storage pools available on a node
VM & Container Inventory
List all VMs (QEMU) and containers (LXC) with their current status
Get detailed status and resource usage of a specific VM or container
List available CT templates and ISO images on a node's storage
Power Management
Start, stop, shutdown, or reboot any VM or container
Provisioning
Create a new LXC container from a template with configurable CPU, memory, disk, networking, hostname, SSH keys, and more
Create a new QEMU VM (empty or with an ISO attached) with configurable CPU, memory, disk, and network
Clone an existing VM or container template into a new instance
Notable Limitation: There is no destroy/delete tool — removing VMs or containers must be done directly in the Proxmox UI.
Allows interaction with a Proxmox VE cluster via its REST API, providing tools for managing VMs, containers, nodes, storage, and templates.
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., "@proxmox-mcp list all resources on the cluster"
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.
mcp-proxmox
MCP server exposing your Proxmox VE cluster to Claude Code via the Proxmox REST API.
1. Create a Proxmox API token
On the Proxmox host (or via the web UI):
# Create a dedicated user
pveum user add mcp@pve
# Create a role with the permissions needed for this server.
# Start with PVEVMAdmin (covers create/clone/start/stop for VMs and CTs)
# plus PVEAuditor (read-only access to nodes/storage).
pveum aclmod / -user mcp@pve -role PVEVMAdmin
pveum aclmod / -user mcp@pve -role PVEAuditor
# Create an API token for that user (copy the secret shown, it's only displayed once)
pveum user token add mcp@pve mcp-token --privsep 0This gives the token the same permission scope as the user. --privsep 0 means the
token inherits the user's full permissions (simpler). Set --privsep 1 and assign
ACLs to the token specifically if you want tighter scoping.
Note on "no delete" by design: the role above does not grant VM.Allocate
removal/destroy actions are still possible under PVEVMAdmin in some Proxmox
versions — if you want to be stricter, create a custom role excluding
VM.Config.* removal privileges. This server itself does not expose a destroy
tool, but a sufficiently broad token could still be used for destructive actions
via raw API calls if compromised. Keep the secret safe.
Related MCP server: Proxmox MCP Server
2. Configure environment variables
export PROXMOX_HOST="https://192.168.100.10:8006" # your Proxmox node, port 8006
export PROXMOX_TOKEN_ID="mcp@pve!mcp-token"
export PROXMOX_TOKEN_SECRET="<the-uuid-secret-from-step-1>"
export PROXMOX_TLS_INSECURE="true" # set if using the default self-signed certPut these in a .env file or your shell profile — do not commit them.
3. Build
npm install
npm run build4. Register with Claude Code
Add to your Claude Code MCP config (e.g. ~/.config/claude-code/mcp.json or via
claude mcp add):
{
"mcpServers": {
"proxmox": {
"command": "node",
"args": ["/absolute/path/to/mcp-proxmox/dist/index.js"],
"env": {
"PROXMOX_HOST": "https://192.168.100.10:8006",
"PROXMOX_TOKEN_ID": "mcp@pve!mcp-token",
"PROXMOX_TOKEN_SECRET": "your-secret-here",
"PROXMOX_TLS_INSECURE": "true"
}
}
}
}Run this on a machine with network access to your Proxmox API (VLAN 100 or
wherever 192.168.100.x is reachable — e.g. your workstation on VLAN 10, or
an LXC you SSH into).
Available tools
Tool | Description |
| List cluster nodes and status |
| CPU/memory/uptime for a node |
| Storage pools on a node |
| All VMs and CTs on a node with status |
| Available CT templates / ISOs |
| Status of a specific VM/CT |
| start / stop / shutdown / reboot a VM/CT |
| Create a new LXC container from a template |
| Create a new empty QEMU VM (optionally with ISO) |
| Clone a VM/CT template |
There is intentionally no destroy/delete tool. Removing VMs/CTs should be done directly in the Proxmox UI.
Notes
VMIDs must be unique cluster-wide — check
list_resourcesbefore creating.net0strings follow Proxmox syntax, e.g.name=eth0,bridge=vmbr0,ip=192.168.100.50/24,gw=192.168.100.1for static IP on VLAN 100, orip=dhcpfor DHCP.For LXC templates, download them first via
pveam available/pveam downloadon the node, or via the Proxmox UI (Storage → CT Templates).
Available Tools
10 toolsclone_resourceB
Clone an existing VM or container template to create a new one. Requires confirming the configuration with the user before calling.
Inputs: node (required), type (required), templateVmid (required), newVmid (required), +3 more.
create_lxcA
Create a new LXC container from a template. Requires confirming the configuration with the user before calling.
Inputs: node (required), vmid (required), ostemplate (required), hostname (required), +9 more.
create_vmB
Create a new QEMU VM (empty, optionally with an ISO attached for OS installation). Requires confirming the configuration with the user before calling.
Inputs: node (required), vmid (required), name (required), storage (required), +6 more.
get_node_statusA
Get detailed status (CPU, memory, uptime) for a specific node.
Inputs: node (required).
get_resource_statusB
Get current status (running/stopped, resource usage) of a specific VM or container.
Inputs: node (required), type (required), vmid (required).
list_nodesA
List all nodes in the Proxmox cluster with their status.
Inputs: no named parameters.
list_resourcesA
List all VMs (qemu) and containers (lxc) on a node with their current status.
Inputs: node (required).
list_storageB
List storage pools available on a node.
Inputs: node (required).
list_templatesA
List available CT templates and ISO images on a node's storage.
Inputs: node (required).
power_actionB
Start, stop, shutdown, or reboot a VM or container.
Inputs: node (required), type (required), vmid (required), action (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Each tool has a clear, distinct purpose: creation, cloning, status queries, listing, and power actions. No two tools overlap in functionality, minimizing confusion for an agent.
All tools follow a consistent snake_case verb_noun pattern (e.g., create_vm, list_nodes), making the naming predictable and easy to navigate.
With 10 tools, the server is well-scoped for Proxmox management, covering essential operations without unnecessary bloat or deficit.
Core CRUD-like operations are present: create, read (list/status), update (power action), but delete functionality is missing. This minor gap prevents full lifecycle management.
Maintenance
Related MCP Connectors
Manage Vozora VPS servers, SSH keys, firewalls, DNS and usage from an AI agent.
Provides capabilities that let LLM agents perform a range of infrastructure management tasks.
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Create projects, nodes, and tasks in UluP Spaces by conversation with Claude.
Related MCP Servers
- AlicenseCqualityDmaintenanceEnables management of Proxmox VE infrastructure through natural language, providing 120+ tools to control virtual machines, containers, storage, cluster resources, users, and network configurations via the Proxmox API.10022 npmMIT
- AlicenseBqualityDmaintenanceEnables Claude to manage Proxmox VE infrastructure — VMs, LXC containers, snapshots, storage, and more.372MIT
- AlicenseCqualityDmaintenanceEnables management of Proxmox VE environments, including VMs, containers, storage, and cluster operations through natural language.7653 npmMIT
- AlicenseNot gradedqualityDmaintenanceEnables Claude to manage a Proxmox VE host through natural language, including guest lifecycle, snapshots, host status monitoring, and shell execution via a companion bridge.22 npm1Apache 2.0