drumfire-proxmox-mcp

Un servidor MCP remoto que permite a Claude gestionar el clúster Proxmox de DRUMFIRE a través del chat: inventario, control de energía, cambios de configuración en vivo, creación/clonación de máquinas virtuales y contenedores, instantáneas, visibilidad de red/cortafuegos/clúster, ejecución de comandos dentro de un invitado y envío de 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 reciente 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 existen 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 presentes en el código, por lo que no pueden ocurrir a través de este servidor ni por error.

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

Related MCP server: ProxmoxEmCP

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 «permisibles» para ejecutarlas sin pedir permiso primero, según cómo lo acotaste — nada de lo que hay aquí es inherentemente destructivo.

• run_guest_command: ejecuta lo que se le indique dentro del invitado, equivalente a acceso SSH/RDP. Apropiada para diagnósticos y cambios rutinarios; se le instruye a Claude a hacer una pausa y confirmar contigo antes de cualquier cosa que parezca destructiva o irreversible dentro del invitado.

• Nada en este servidor elimina ni revierte una VM, contenedor, disco o instantánea. Esa es la verdadera red de seguridad, no los permisos del token de Proxmox — consulta el rol más abajo, que sí concede VM.Allocate (necesario para la creación, y que Proxmox también utiliza para la eliminación — no hay forma de separarlos a nivel de permisos).

1. Crea 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.

   Deliberadamente excluye VM.Snapshot.Rollback (la reversión descarta el estado actual del disco — algo genuinamente destructivo) y VM.Backup/VM.Migrate/VM.Console (no necesarios para nada de lo que hace este servidor). Como se ha mencionado, VM.Allocate es necesario para create_vm/create_container/clone_vm y Proxmox también lo utiliza para la eliminación de invitados — no hay 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 estricta a nivel de credenciales en el día a día y conceder la creación solo temporalmente, puedes crear en su lugar un segundo token más restringido (este mismo rol menos VM.Allocate/VM.Config.*) y cambiar qué secreto usa este Worker cuando realmente quieras crear/reconfigurar algo — la cuestión del equilibrio anterior se decantó por un solo token por simplicidad, pero nada aquí lo exige.

2. Centro de datos → Permisos → Usuarios → Añadir 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 del token p. ej. homelab-mcp. Deja marcada «Separación de privilegios» y concede el mismo ACL / → ClaudeHomelabOps al propio token. Copia el ID del token (claude-agent@pve!homelab-mcp) y el secreto (se muestra una sola vez) — necesitarás ambos más 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 que el QEMU Guest Agent se esté ejecutando 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á (se incluye en la ISO de virtio-win como qemu-ga-x86_64.msi) y asegúrate de que el servicio de Windows «QEMU Guest Agent» se está ejecutando.

3. Anota en 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, por lo que las escrituras de archivos necesitan una ruta absoluta completa, p. ej. C:\Users\<username>\Documents\net-worth\data.json, no una relativa.

3. Despliega

(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/conecta en Cloudflare Workers Builds y ejecuta el despliegue por ti. Aún no será utilizable, sin embargo — consulta el 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, lo cual está bien porque puede ser público):

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>.

Revisa también la variable normal (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 de texto plano, no como secreto), o edita wrangler.jsonc y vuelve a desplegar.

5. Añádelo 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 en cada solicitud la cabecera Authorization: Bearer <MCP_BEARER_TOKEN> antes de hacer nada — sin ella, cada llamada a herramienta recibe un 401. Si la configuración de tu conector de Claude te permite adjuntar una cabecera/clave de API personalizada, establece esa cabecera allí. Si no lo permite, las dos opciones son:

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

• Como alternativa de menor seguridad, elimina la comprobación del token de portador 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 se recomienda 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 extrae datos de Firefly III (ya conectado), construye el JSON que la calculadora espera y llama a update_networth_calculator con ese JSON como cadena.

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

Nota sobre los permisos: Los requisitos exactos de privilegios de Proxmox para los endpoints de reglas de firewall y algunos de lectura de red varían un poco según la versión, y el rol anterior es un mapeo de mejor esfuerzo, no algo que se haya probado contra tu versión específica de Proxmox. Si una llamada de 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 solo volver a confirmar que Sys.Audit está aplicado en /, no solo en una subruta).