drumfire-proxmox-mcp

Un servidor MCP remoto que permite a Claude gestionar el clúster DRUMFIRE de Proxmox a través del chat: inventario, control de energía, cambios de configuración en vivo, creación/clonación de VMs y contenedores, instantáneas, visibilidad de red/firewall/clúster, ejecutar comandos dentro de un invitado y enviar un archivo directamente al sistema de archivos de una VM a través del QEMU Guest Agent (usado aquí para actualizar la calculadora de patrimonio neto que se ejecuta en la VM 107 con una exportación nueva de Firefly III).

Es un Cloudflare Worker, desplegado de la misma manera que el servidor MCP existente de Firefly III: haz clic en el botón, configura algunos secretos, añádelo a Claude como conector personalizado.

Lo que deliberadamente NO hace

No hay herramientas de eliminación de VM/contenedor/disco/instantánea ni de reversión de instantáneas — no es "preguntar antes", simplemente no están en el código, así que no pueden ocurrir a través de este servidor ni por error.

Dicho esto, lee la nota de seguridad a continuación: como la creación de VMs/contenedores está dentro del alcance, el token de Proxmox subyacente técnicamente también puede eliminarlos (Proxmox vincula esos permisos entre sí) — la garantía aquí está impuesta por software (no existe tal herramienta, y se le indica a Claude que siempre pregunte antes de cualquier acción destructiva), no es un muro duro a nivel de credenciales como lo era la v1 de este servidor. Ver "Modelo de seguridad" más abajo.

Related MCP server: proxmox-mcp

Herramientas que expone este servidor

Modelo de seguridad

• Herramientas de energía/estado/configuración/creación/clonación/creación de instantáneas: se consideran "válidas" para ejecutarlas sin preguntar antes, según cómo lo definiste — nada de esto es inherentemente destructivo.

• run_guest_command: ejecuta lo que se le indique dentro del invitado, equivalente a acceso SSH/RDP. Apto para diagnósticos y cambios rutinarios; se le indica a Claude que se detenga y confirme contigo antes de cualquier cosa que parezca destructiva o irreversible dentro del invitado.

• Nada en este servidor elimina o revierte una VM, contenedor, disco o instantánea. Ese es el respaldo real, no los permisos del token de Proxmox — ver el rol a continuación, que sí otorga VM.Allocate (requerido para la creación, y que Proxmox también usa para la eliminación — no hay forma de separarlos a nivel de permisos).

1. Crear un token de API de Proxmox con ámbito limitado

No reutilices un token de root/admin. En la interfaz web de Proxmox:

1. Centro de datos → Permisos → Roles → Crear Nombre: ClaudeHomelabOps. Privilegios: VM.Audit, VM.Monitor, VM.PowerMgmt, Sys.Audit, VM.Allocate, VM.Clone, VM.Snapshot, VM.Config.CPU, VM.Config.Memory, VM.Config.Disk, VM.Config.Network, VM.Config.Options, VM.Config.HWType, VM.Config.CDROM, VM.Config.Cloudinit.

   Excluye deliberadamente VM.Snapshot.Rollback (la reversión descarta el estado actual del disco — genuinamente destructiva) y VM.Backup/VM.Migrate/VM.Console (no son necesarios para nada de lo que hace este servidor). Como se indicó antes, VM.Allocate es necesario para create_vm/create_container/clone_vm y Proxmox también lo usa para la eliminación de invitados — no existe una división más granular disponible, así que la garantía de "no se puede eliminar" aquí proviene de que este servidor simplemente no tiene una herramienta de eliminación, no de los permisos del token.

   Si prefieres mantener la garantía más dura a nivel de credenciales en el día a día y conceder la creación solo temporalmente, puedes crear un segundo token más restringido (este mismo rol sin VM.Allocate/VM.Config.*) y cambiar qué secreto usa este Worker cuando realmente quieras crear/reconfigurar algo — la disyuntiva anterior se resolvió con un solo token por simplicidad, pero nada aquí lo requiere.

2. Centro de datos → Permisos → Usuarios → Añadir añade un usuario dedicado, p. ej. claude-agent@pve (no necesita contraseña, solo se autenticará mediante token de API).

3. Centro de datos → Permisos → Añadir → Ruta /, Usuario claude-agent@pve, Rol ClaudeHomelabOps.

4. Centro de datos → Permisos → Tokens de API → Añadir → Usuario claude-agent@pve, ID de token p. ej. homelab-mcp. Deja marcada la opción "Separación de privilegios" y concede al propio token la misma ACL / → ClaudeHomelabOps. Copia el Token ID (claude-agent@pve!homelab-mcp) y el secreto (se muestra una sola vez) — los necesitarás ambos abajo.

2. Asegúrate de que el agente invitado de la VM de la calculadora esté habilitado

Las herramientas write_vm_file / update_networth_calculator necesitan el QEMU Guest Agent ejecutándose dentro de la VM 107 (VM-OnPremTest):

1. En la pestaña Opciones de la VM en Proxmox, confirma que "QEMU Guest Agent" está habilitado.

2. Dentro de la VM Windows, instala el servicio del agente invitado si aún no está (viene en la ISO de virtio-win como qemu-ga-x86_64.msi) y asegúrate de que el servicio de Windows "QEMU Guest Agent" esté en ejecución.

3. Anota bajo qué cuenta de usuario de Windows se encuentra la carpeta de datos de la aplicación — el servicio del agente invitado se ejecuta como SYSTEM, así que las escrituras de archivos necesitan una ruta absoluta completa, p. ej. C:\Users\<username>\Documents\net-worth\data.json, no una relativa.

3. Desplegar

(Primero sube este repositorio a GitHub y luego reemplaza REPLACE_WITH_THIS_REPO_URL arriba con https://github.com/<you>/<repo> — GitHub no permite que el botón enlace a sí mismo antes de que el repositorio exista.)

Al hacer clic en el botón, el repositorio se bifurca/se conecta en Cloudflare Workers Builds y ejecuta el despliegue por ti. Aún no será utilizable, sin embargo — ver paso 4.

Despliegue manual (alternativa al botón)

npm install
npx wrangler secret put PROXMOX_TOKEN_ID
npx wrangler secret put PROXMOX_TOKEN_SECRET
npx wrangler secret put MCP_BEARER_TOKEN   # any long random string you generate
npx wrangler deploy

4. Después de desplegar, configura los secretos

Tanto si usaste el botón como la CLI, se requieren tres secretos que intencionadamente no están en este repositorio (no están en wrangler.jsonc, que puede ser público sin problema):

Configúralos en el panel de Cloudflare en tu Worker → Configuración → Variables y secretos → Añadir → Cifrar, o mediante npx wrangler secret put <NAME>.

Comprueba también la variable (no secreta) NETWORTH_VM_PATH en wrangler.jsonc — viene con un marcador de posición (C:\Users\CHANGE_ME\Documents\net-worth\data.json) que necesita el nombre de usuario real de Windows del paso 2. Edítala en el panel de Cloudflare en la misma página de Variables y secretos (como variable en texto plano, no como secreto), o edita wrangler.jsonc y vuelve a desplegar.

5. Añadirlo a Claude como conector personalizado

En la configuración de conectores de Claude, añade un conector personalizado que apunte a:

https://<your-worker-subdomain>.workers.dev/mcp

Este Worker comprueba cada solicitud para ver si tiene Authorization: Bearer <MCP_BEARER_TOKEN> antes de hacer nada — sin ello, cada llamada de herramienta recibe un 401. Si tu configuración de conector de Claude te permite adjuntar una cabecera/clave de API personalizada, configura esa cabecera allí. Si no lo permite, las dos opciones son:

• Pon una política de Cloudflare Access delante de la ruta del Worker (recomendado: es la forma estándar de restringir un endpoint MCP personal cuando el cliente no puede enviar una cabecera personalizada), o

• Como alternativa de menor seguridad, elimina la comprobación del bearer token en src/index.ts (fetch(), al principio de la función) y confía en que la propia URL del Worker sea imposible de adivinar. No recomendado para nada que pueda tocar Proxmox.

6. Pruébalo

Una vez conectado, en un chat de Claude: "lista las VMs en drumfire03" o "cuál es el estado de la VM 107" deberían devolver datos reales. Para el flujo de trabajo del patrimonio neto, Claude obtiene datos de Firefly III (ya conectado), construye el JSON que espera la calculadora y llama a update_networth_calculator con ese JSON como cadena.

Una vez que funcione, prueba también las herramientas más nuevas — "comprueba la salud del clúster", "cuál es la IP real de la VM 107 ahora mismo", "clona VM-OnPremTest en una copia de prueba", "aumenta esa VM a 4 núcleos".

Nota sobre permisos: los requisitos exactos de privilegios de Proxmox para los endpoints de reglas de firewall y algunos endpoints de lectura de red varían un poco según la versión, y el rol anterior es una asignación de mejor esfuerzo, no algo probado contra tu versión específica de Proxmox. Si una llamada a una herramienta devuelve un 403, el mensaje de error incluye la respuesta real de Proxmox; la solución casi siempre es añadir un privilegio más a ClaudeHomelabOps (normalmente basta con volver a confirmar que Sys.Audit está aplicado en /, no solo en una subruta).