mcp-proxmox is an MCP (Model Context Protocol) server for Proxmox VE cluster management, allowing users to configure, manage, and monitor infrastructure in natural language through AI assistants such as Claude, Cursor, and Cline.
Purpose Perform daily operations and maintenance on a Proxmox VE cluster through natural language, including creating virtual machines and containers, managing snapshots, browsing storage, backup and restore, templates and cloud-init configuration, firewall rule management, and migration between nodes.
Main Capabilities
- Virtual machines and containers: create, delete, clone, adjust CPU/memory/disk, start, stop, and restart.
- Snapshots: create, roll back, delete.
- Storage: list storage pools, browse contents, view available ISO images.
- Backup and restore: back up virtual machines, view backups, restore backups.
- Command execution: execute commands inside a virtual machine (requires qemu-guest-agent, only supports QEMU virtual machines, does not support LXC).
- Console interaction: screenshots, send keyboard input (only QEMU virtual machines, requires VM.Console permission, text input is based on the US keyboard layout, non-ASCII characters are not supported).
- Templates and cloud-init: list templates, convert virtual machines to templates, configure cloud-init parameters.
- Firewall: view and add firewall rules.
- Migration: migrate virtual machines/containers between nodes.
- Nodes and tasks: view node status, tasks, network bridges, etc.
Usage
- Create an API Token in the Proxmox Web UI: go to Datacenter > Permissions > API Tokens, click Add to create a token for a user. You can uncheck "Privilege Separation" to obtain full permissions, or assign permissions as needed (such as VM.Audit, VM.PowerMgmt, VM.Snapshot, VM.Allocate, VM.Clone, Datastore.Audit, Datastore.AllocateSpace, Sys.Audit, VM.Config.Disk, VM.Config.CPU, VM.Config.Memory, VM.Monitor, VM.Console, VM.Migrate, Sys.Modify, VM.Config.Cloudinit).
- Set environment variables or create a .env file, containing at least PROXMOX_HOST, PROXMOX_TOKEN_ID, PROXMOX_TOKEN_SECRET.
- Configure in the MCP client: Claude Desktop can add it to ~/.claude/claude_desktop_config.json; Claude Code can add it to .claude/settings.json or ~/.claude/settings.json; Cursor can use the same configuration in Settings > MCP.
- After connecting, you can issue instructions to the AI assistant in natural language, such as listing virtual machines and their status, viewing memory usage, shutting down containers, creating snapshots, viewing CPU usage, creating new virtual machines, cloning, backing up, restoring, executing commands, taking screenshots, adjusting resources, managing the firewall, migrating, managing templates and cloud-init, etc.
Destructive Operation Confirmation Operations such as stop_guest, reboot_guest, rollback_snapshot, delete_snapshot, delete_guest, resize_guest, restore_backup, delete_firewall_rule, migrate_guest, create_template require explicitly passing confirm=true. The first call returns an impact warning, and only the second call with confirmation will execute.
Applicable Scenarios Suitable for operations personnel, home lab users, and development teams that need to manage Proxmox VE clusters in a conversational manner, especially for quickly checking status, performing routine operations and maintenance tasks, and automating operations.
Limitations and Notes
- exec_command requires qemu-guest-agent to be installed and running inside the virtual machine, and does not support LXC containers.
- Console tools only support QEMU virtual machines, text input depends on the US keyboard layout, and non-ASCII input is not supported.
- Common issues: missing environment variables, 403 insufficient permissions, exec_command failure caused by guest-agent or LXC, missing mcp.server.fastmcp module (requires upgradingto mcp-proxmox 1.2.2 or later, which pins mcp<2), self-signed certificates, or connection errors (Proxmox commonly uses port 8006; for home labs, PROXMOX_VERIFY_SSL=false can be set).
