felhen-ai/mcp-proxmox

MCP server for managing Proxmox VE clusters through AI assistants like Claude, Cursor, and Cline.
Provision, manage, and monitor your entire Proxmox infrastructure through natural language. Create VMs and containers, manage snapshots, browse storage, and more.
## Quick Start
bash
# Run directly with uvx (no install needed)
uvx mcp-proxmox
# Or install with pip
pip install mcp-proxmox
## Configuration
Set these environment variables (or create a .env file):
bash
PROXMOXHOST=192.168.1.100 # Your Proxmox VE host
PROXMOXTOKENID=user@pam!mcp # API token ID
PROXMOXTOKENSECRET=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx # API token secret
Optional:
bash
PROXMOXPORT=8006 # Default: 8006
PROXMOXVERIFYSSL=false # Default: false
### Creating a Proxmox API Token
1. Log into your Proxmox web UI
2. Go to Datacenter > Permissions > API Tokens
3. Click Add and create a token for your user
4. Uncheck "Privilege Separation" for full access, or assign specific permissions:
VM.Audit — read VM/CT status and config
VM.PowerMgmt — start/stop/shutdown/reboot
VM.Snapshot — create/rollback/delete snapshots
VM.Allocate — create/delete/clone VMs and containers
VM.Clone — clone operations
Datastore.Audit — list storages and browse content
Datastore.AllocateSpace — allocate disk space for new VMs/CTs
Sys.Audit — read node status and tasks
VM.Config.Disk — resize disks
VM.Config.CPU — change CPU allocation
VM.Config.Memory — change memory allocation
VM.Monitor — access QEMU monitor (for metrics)
VM.Console — console interaction tools (screenshots, keyboard input)
VM.Migrate — migrate VMs/CTs between nodes
Sys.Modify — manage firewall rules
VM.Config.Cloudinit — configure cloud-init parameters
## Integration
### Claude Desktop
Add to ~/.claude/claudedesktopconfig.json:
json
"mcpServers": {
"proxmox": {
"command": "uvx",
"args": ["mcp-proxmox"],
"env": {
"PROXMOXHOST": "192.168.1.100",
"PROXMOXTOKENID": "user@pam!mcp",
"PROXMOXTOKENSECRET": "your-token-secret"
### Claude Code
Add to .claude/settings.json or ~/.claude/settings.json:
json
"mcpServers": {
"proxmox": {
"command": "uvx",
"args": ["mcp-proxmox"],
"env": {
"PROXMOXHOST": "192.168.1.100",
"PROXMOXTOKENID": "user@pam!mcp",
"PROXMOXTOKENSECRET": "your-token-secret"
### Cursor
Add to Cursor Settings > MCP with the same configuration as above.
## Available Tools
### Discovery
| Tool | Description |
| listnodes | List all cluster nodes with CPU, memory, and uptime |
| getnodestatus | Detailed node info: CPU model, memory, disk, versions |
| listvms | List QEMU VMs (filter by node or status) |
| listcontainers | List LXC containers (filter by node or status) |
| getgueststatus | Detailed VM/CT status by VMID (auto-detects type and node) |
### Lifecycle
| Tool | Description |
| startguest | Start a stopped VM or container |
| stopguest | Force-stop (requires confirmation) |
| shutdownguest | Graceful ACPI/init shutdown |
| rebootguest | Reboot (requires confirmation) |
### Storage
| Tool | Description |
| liststorages | List storage pools with capacity and usage (filter by node) |
| liststoragecontent | Browse ISOs, templates, backups, and disk images |
### Provisioning
| Tool | Description |
| createvm | Create a QEMU VM with configurable CPU, memory, disk, ISO, and network |