# 🧠⚙️ 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.

---

## 🚀 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:

```bash
chmod +x install.sh
./install.sh
```

### On Windows (PowerShell)

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

```powershell
.\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):

```bash
# 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:
```env
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:
     ```bash
     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`

```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:
```bash
agy mcp add proxmox "/absolute/path/to/.venv/bin/python" "/absolute/path/to/server.py"
```

---

## 🧰 Available MCP Tools

| Tool | Description |
| :--- | :--- |
| `execute_command(vmid, command, timeout?)` | **Executes shell commands inside the guest OS** and returns stdout, stderr, and exit code. |
| `read_guest_file(vmid, file_path)` | Reads files inside the guest OS filesystem (e.g. configs, logs). |
| `write_guest_file(vmid, file_path, content)` | Writes or updates files inside the guest OS filesystem. |
| `get_guest_os_info(vmid)` | Queries guest OS version, kernel, architecture, timezone, and logged-in users. |
| `list_nodes()` | Lists all nodes in the cluster, online status, CPU/RAM usage, and uptime. |
| `get_node_metrics(node?)` | Returns real-time metrics for CPU, RAM, swap, disk rootfs, and kernel. |
| `list_vms(node?)` | Lists all VMs (QEMU) and LXC containers with CPU, memory, and status. |
| `get_vm_details(vmid, node?, vm_type?)` | Retrieves detailed VM/LXC hardware specs, configuration, and guest agent network IPs. |
| `power_manage(vmid, action, node?, vm_type?)` | Controls power: `start`, `stop`, `shutdown`, `reboot`, `reset`, `suspend`, `resume`. |
| `manage_snapshots(vmid, action, snapname?, ...)` | Manages snapshots: `list`, `create`, `rollback`, `delete`. |

---

## 💬 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](https://www.python.org/)
* [Model Context Protocol (FastMCP)](https://modelcontextprotocol.io/)
* [Proxmoxer](https://proxmoxer.github.io/)
* [Paramiko](https://www.paramiko.org/)

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