🔍 esxi-readonly-mcp

Diagnóstico completo de VMware ESXi desde tu asistente de IA, sin poder romper nada.

Un servidor MCP que le da a Claude (o a cualquier cliente MCP) visibilidad total sobre tu host ESXi — CPU Ready, latencia de disco, snapshots, espacio real, salud del hardware, eventos — sin una sola herramienta de escritura.

¿Por qué?

Tenés un ESXi standalone (sin vCenter), el ERP anda lento y alguien propone gastar miles de dólares en hardware. Antes de comprar, necesitás saber qué recurso es el cuello de botella de verdad. Eso implica mirar métricas que el Host Client esconde o no guarda (CPU Ready, Co-Stop, latencia por disco virtual), cruzar el espacio provisionado contra el real y revisar snapshots, logs y sensores.

Con este MCP le preguntás a Claude "¿por qué está lenta la VM del ERP?" y él mismo consulta el host, cruza los datos y te responde con números.

Y como vas a darle acceso a un asistente de IA a tu infraestructura de producción, el servidor no expone ninguna operación que modifique algo: no puede apagar, borrar, crear, consolidar ni reconfigurar nada. Combinado con un usuario de ESXi con rol de solo lectura, la garantía es doble.

Related MCP server: VMware-Monitor

✨ Qué podés preguntarle

"Hacé un diagnóstico completo del host y decime cuál es el cuello de botella."

"¿Qué VM tiene más CPU Ready en la última hora?"

"¿Cuánto ocupa realmente cada VM en cada datastore?"

"¿Hay snapshots de más de 3 días?"

"¿Qué archivos grandes hay en los datastores que no pertenecen a ninguna VM?"

"¿Algún sensor de hardware en amarillo o rojo? ¿Hubo errores de disco esta semana?"

"¿Tengo overcommit de CPU? ¿Cuántas vCPU tengo por core físico?"

"¿Conviene más comprar RAM o cambiar el procesador?"

🧰 Herramientas

Todas las respuestas vienen con valores de referencia (por ejemplo: CPU Ready > 10 % = contención) para que el asistente pueda interpretarlas sin adivinar.

🔒 Seguridad: cómo se garantiza que es solo lectura

1. En el código. El servidor solo lee propiedades y llama a estos métodos de la API de vSphere, todos de consulta:

No hay ninguna herramienta MCP para modificar nada, y el servidor le indica al asistente que no existen.

2. En ESXi. Usá un usuario dedicado con un rol de solo lectura (paso 1 de la instalación). Aunque algo intentara escribir, ESXi lo rechazaría. verificar_permisos te confirma que quedó bien configurado:

{ "usuario": "mcp-readonly", "roles": ["ReadOnly+Browse"],
  "privilegios_escritura_detectados": [], "solo_lectura_garantizado_por_ESXi": true }

3. Credenciales. La contraseña nunca va en archivos de configuración: se guarda en el almacén de credenciales del sistema operativo (Administrador de credenciales de Windows, Keychain en macOS, Secret Service en Linux) mediante keyring. Las claves de licencia se muestran enmascaradas.

🚀 Instalación

Requisitos

• uv (se encarga de Python y de las dependencias)

• Acceso por red al puerto 443 del ESXi

• Un cliente MCP: Claude Code, Claude Desktop u otro

1. Crear un usuario de solo lectura en ESXi

En el Host Client (https://<ip-esxi>/ui):

1. Manage → Security & users → Roles → Add role — nombre ReadOnly+Browse:

   • ✅ System (Anonymous, Read, View)

   • ✅ Datastore → Browse datastore — solo ese; nada de Delete, FileManagement ni AllocateSpace

2. Manage → Security & users → Users → Add user — por ejemplo mcp-readonly. Dejá Enable shell access desmarcado.

3. Host → Actions → Permissions → Add user — elegí mcp-readonly, el rol ReadOnly+Browse y marcá Propagate to all children.

Sin Browse datastore el MCP funciona igual, pero top_archivos solo ve archivos de VMs registradas (no ISOs ni huérfanos) y el espacio "usado" de discos thin es aproximado.

2. Guardar la contraseña en el almacén del sistema

uvx esxi-readonly-mcp --set-password

Te pide el usuario de ESXi y la contraseña (sin mostrarla) y la guarda en el almacén de credenciales del sistema. No hace falta clonar nada: uvx descarga el paquete de PyPI y lo ejecuta.

3. Registrar el servidor en tu cliente MCP

Claude Code

claude mcp add esxi-readonly --scope user \
  -e ESXI_HOST=192.0.2.10 -e ESXI_USER=mcp-readonly \
  -- uvx esxi-readonly-mcp

Claude Desktop u otro cliente (en claude_desktop_config.json o equivalente):

{
  "mcpServers": {
    "esxi-readonly": {
      "command": "uvx",
      "args": ["esxi-readonly-mcp"],
      "env": { "ESXI_HOST": "192.0.2.10", "ESXI_USER": "mcp-readonly" }
    }
  }
}

En Windows usá la ruta completa a uvx.exe si el cliente no lo encuentra en el PATH (por ejemplo C:\\Users\\<usuario>\\.local\\bin\\uvx.exe).

Reiniciá el cliente y pedile: "verificá los permisos del MCP de ESXi".

Desde el código fuente

git clone https://github.com/nicolasboattini/esxi-readonly-mcp.git
cd esxi-readonly-mcp
uv sync
uv run esxi-readonly-mcp --set-password

Y en el cliente MCP usá uv run --directory /ruta/a/esxi-readonly-mcp esxi-readonly-mcp como comando.

Probar sin cliente MCP

ESXI_HOST=192.0.2.10 ESXI_USER=mcp-readonly uv run python -c "from esxi_readonly_mcp import server; import json; print(json.dumps(server._host_info(), indent=2))"

(En PowerShell: $env:ESXI_HOST="192.0.2.10"; $env:ESXI_USER="mcp-readonly"; uv run python -c "...")

⚙️ Configuración

📈 Historial de performance

Un ESXi sin vCenter guarda solo la última hora de métricas (muestras cada 20 s). Para ver los picos reales de las últimas semanas en horario laboral, el servidor trae un modo recolector que guarda esa hora en una base SQLite local:

uvx esxi-readonly-mcp --collect

Programalo cada hora y después pedile a Claude, por ejemplo: "mostrame el historial de performance de las últimas 4 semanas en horario laboral" (historial_perf(dias=28, solo_horario_laboral=True)).

Windows (Programador de tareas)

[Environment]::SetEnvironmentVariable("ESXI_HOST", "192.0.2.10", "User")
[Environment]::SetEnvironmentVariable("ESXI_USER", "mcp-readonly", "User")

$uvx = (Get-Command uvx).Source
$a  = New-ScheduledTaskAction -Execute $uvx -Argument 'esxi-readonly-mcp --collect'
$t  = New-ScheduledTaskTrigger -Daily -At 7:05am
$t.Repetition = (New-ScheduledTaskTrigger -Once -At 7:05am -RepetitionInterval (New-TimeSpan -Hours 1) -RepetitionDuration (New-TimeSpan -Hours 13)).Repetition
Register-ScheduledTask -TaskName "ESXi perf collect" -Action $a -Trigger $t -User $env:USERNAME

Linux / macOS (cron)

5 7-20 * * 1-5  ESXI_HOST=192.0.2.10 ESXI_USER=mcp-readonly $HOME/.local/bin/uvx esxi-readonly-mcp --collect

La base contiene nombres de VMs y métricas. Por defecto vive en tu carpeta de usuario, fuera de cualquier repo.

🧪 Compatibilidad

⚠️ Limitaciones conocidas

• Métricas históricas: sin vCenter, performance solo ve ~1 hora. Usá --collect + historial_perf.

• Eventos: ESXi standalone guarda los últimos ~1000 eventos. Si un sistema de monitoreo abre sesiones constantemente (por ejemplo, Zabbix mal configurado), eso puede cubrir solo unas horas.

• RAID y discos físicos: salud_hardware los muestra solo si ESXi tiene el proveedor CIM del fabricante (Dell, HPE, Lenovo). Si no, revisalos en iDRAC / iLO / XCC.

• Lista de VIBs/drivers: requiere Host.Config.Image, que también permite modificar la imagen; el MCP no lo pide. Alternativa: esxcli software vib list por SSH.

• Dentro del guest: el MCP ve lo que reporta VMware Tools (unidades, espacio libre, IP), pero no archivos ni procesos dentro de la VM.

🛠️ Solución de problemas

📁 Estructura

esxi-readonly-mcp/
├── src/esxi_readonly_mcp/
│   └── server.py    # servidor MCP + --collect + --set-password
├── pyproject.toml   # paquete PyPI (mcp<2, pyvmomi, keyring)
├── server.json      # ficha para el registro oficial de MCP
├── uv.lock
└── README.md

🤝 Contribuir

Issues y pull requests bienvenidos, sobre todo:

• Pruebas en ESXi 7/8 y vCenter

• Nuevas métricas o chequeos de solo lectura

La regla del proyecto es una sola: ninguna herramienta puede modificar el entorno. Un PR que agregue operaciones de escritura no se va a aceptar, aunque sea "opcional".

Publicar una versión (mantenedores)

1. Actualizar la versión en pyproject.toml y en server.json (dos lugares: version y packages[0].version).

2. Commit, push y tag:

   git tag v0.1.1 && git push origin v0.1.1

3. El workflow release.yml verifica que las versiones coincidan, compila, prueba el paquete, lo publica en PyPI y después en el registro oficial de MCP. Sin tokens: usa OIDC de GitHub.

📄 Licencia

MIT