🧠⚙️ Proxmox MCP for AI (Claude, Cursor & Antigravity)

A powerful, lightweight Model Context Protocol (MCP) server built in Python that enables Artificial Intelligence assistants (Claude Desktop, Cursor, Antigravity, Claude Code, etc.) to manage and monitor your Proxmox VE cluster using natural language.

Instead of dealing with the web interface or complex commands, simply ask your AI: "What is the CPU and RAM usage of the cluster?", "Take a snapshot of VM 104 before updating", "Restart the Jellyfin container", or "Give me a report of all powered-off VMs".

Created by [tirso.log] - Ideal for Homelabs and SysAdmins.

✨ Features

• Natural Language Interaction: Control and monitor your infrastructure directly from your favorite AI client.

• Full Guest Control & Command Execution: Execute shell commands directly inside your VMs (using QEMU Guest Agent via Proxmox REST API) and LXC containers (via SSH pct exec).

• In-Guest File Management: Read and write configuration files or logs directly inside guest machines without manual SSH login.

• Auto-Discovery: Automatically detects nodes, VM types (QEMU vs LXC), and location by VMID—no need to memorize node names!

• Hardware & Health Metrics: Query CPU, RAM, swap, storage, and cluster node status in real time.

• Snapshot Management: List, create, rollback, and delete snapshots effortlessly.

• Power Management: Start, stop, graceful shutdown, reboot, reset, suspend, and resume VMs and LXC containers.

• Secure by Design: Uses Proxmox API Tokens with custom permissions. No root password required for VM operations.

• Cross-Platform Installers: Interactive setup scripts for Linux/macOS (install.sh) and Windows (install.ps1).

• Multi-Client Support: Ready for Claude Desktop, Cursor, Antigravity, VS Code Roo/Cline, and Claude Code.

Related MCP server: mcp-server-proxmox

🚀 Quick Installation

Clone or download this repository to your local machine. The interactive installer handles virtual environment creation, dependency installation, guided .env configuration, and connection testing.

On Linux / macOS (Bash)

Make the script executable and run it:

chmod +x install.sh
./install.sh

On Windows (PowerShell)

Right-click on install.ps1 and select "Run with PowerShell", or execute from your terminal:

.\install.ps1

Note: If you get an execution policy error on Windows, run this first: Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

🔒 1. Generate Proxmox Credentials (Safe Mode)

For security reasons, never connect the AI using the root user. Follow these steps in your Proxmox node shell to create a dedicated user with limited permissions (operating VMs):

# Create user
pveum user add claude-mcp@pve -comment "MCP AI Agent"

# Assign VM admin role (no base host or root network changes)
pveum acl modify /vms -user claude-mcp@pve -role PVEVMAdmin

# Generate the API Token (Save the 'Secret' value that this command prints)
pveum user token add claude-mcp@pve mcp-token --privsep 0

The interactive installer will ask for these values, or you can paste them into your .env file:

PROXMOX_HOST="192.168.1.100"
PROXMOX_PORT="8006"
PROXMOX_USER="claude-mcp@pve"
PROXMOX_TOKEN_NAME="mcp-token"
PROXMOX_TOKEN_VALUE="YOUR_SECRET_VALUE"
PROXMOX_VERIFY_SSL="false"

# [Optional] Only required if you want the AI to run commands inside LXC containers:
PROXMOX_SSH_HOST="192.168.1.100"
PROXMOX_SSH_PORT="22"
PROXMOX_SSH_USER="root"
PROXMOX_SSH_PASSWORD="YOUR_SSH_PASSWORD"   # Or use PROXMOX_SSH_KEY_PATH="/home/user/.ssh/id_rsa"
PROXMOX_SSH_KEY_PATH=""

⚡ 2. How the AI Executes Commands Inside Machines

Virtual Machines (QEMU / KVM)

• How it works: Uses Proxmox's native REST API via the QEMU Guest Agent (/nodes/{node}/qemu/{vmid}/agent/exec).

• Requirements:

  1. In Proxmox VE: VM > Options > QEMU Guest Agent > set to Enabled.

  2. Inside the guest OS: Install and start the agent:

     sudo apt update && sudo apt install qemu-guest-agent -y
     sudo systemctl enable --now qemu-guest-agent

• No open ports or SSH required: The communication travels over an isolated hypervisor virtio channel.

Linux Containers (LXC)

• How it works: Because Proxmox does not have a native REST API endpoint to run arbitrary commands inside LXCs, the MCP server connects to your Proxmox host via SSH and executes pct exec <vmid> -- <command>.

• Requirements: Configure PROXMOX_SSH_USER and password or key path in your .env.

🔗 3. Connecting to Your AI Clients

The installer will output the exact configuration block tailored with your machine's absolute paths.

Claude Desktop

Add to your claude_desktop_config.json:

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "proxmox": {
      "command": "/absolute/path/to/proxmox-mcp-ia/.venv/bin/python",
      "args": ["/absolute/path/to/proxmox-mcp-ia/server.py"]
    }
  }
}

Cursor / VS Code (Roo Code / Cline)

Add the same block to your ~/.cursor/mcp.json or .cursor/mcp.json.

Antigravity / Claude Code (CLI)

Register the server directly from your terminal:

agy mcp add proxmox "/absolute/path/to/.venv/bin/python" "/absolute/path/to/server.py"

🧰 Available MCP Tools

💬 Usage Examples

• "Ejecuta apt update && apt upgrade -y dentro de la máquina 104 y muéstrame el resultado."

• "Lee el archivo /etc/nginx/nginx.conf de la máquina 102 para revisar la configuración de puertos."

• "Comprueba el uso de disco dentro de la VM 101 con df -h."

• "Crea un snapshot de la máquina 104 llamado 'pre-update' antes de tocar nada."

• "Dame un resumen del estado del clúster y el uso de CPU/RAM de los nodos."

• "Lista todas las máquinas virtuales y dime cuáles están apagadas."

• "Reinicia de forma segura el contenedor LXC de Jellyfin."

🛠️ Technologies Used

• Python 3

• Model Context Protocol (FastMCP)

• Proxmoxer

• Paramiko

License: MIT - Use it, modify it, and share it freely.