esxi-readonly-mcp

<!-- mcp-name: io.github.nicolasboattini/esxi-readonly-mcp -->
<div align="center">

# 🔍 esxi-readonly-mcp

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

Un servidor [MCP](https://modelcontextprotocol.io) 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**.

[![PyPI](https://img.shields.io/pypi/v/esxi-readonly-mcp?logo=pypi&logoColor=white)](https://pypi.org/project/esxi-readonly-mcp/)
![Python](https://img.shields.io/badge/python-3.10%2B-3776AB?logo=python&logoColor=white)
![MCP](https://img.shields.io/badge/MCP-stdio-6E56CF)
![ESXi](https://img.shields.io/badge/ESXi-6.7%2B-607078?logo=vmware&logoColor=white)
![Solo lectura](https://img.shields.io/badge/modo-solo%20lectura-2EA44F)
![Licencia](https://img.shields.io/badge/licencia-MIT-blue)

[![Listed on mcpservers.org](https://mcpservers.org/badge.svg)](https://mcpservers.org/servers/nicolasboattini/esxi-readonly-mcp)

</div>

---

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

## ✨ 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

| Herramienta | Qué devuelve |
|---|---|
| `diagnostico_completo` | Todo lo de abajo en una sola llamada — el punto de partida ideal |
| `host_info` | Fabricante, modelo, serie, BIOS, CPU (cores / hilos / HT), RAM total y usada, versión y build de ESXi, uptime, política de energía, controladoras de storage |
| `salud_hardware` | Sensores (temperaturas, ventiladores, fuentes, voltajes), memoria, CPU y estado de RAID/discos físicos si el host tiene el proveedor CIM del fabricante. Lista primero lo que no está en verde |
| `config_host` | Licencia (clave enmascarada) y vencimiento, NTP y **desfase real del reloj**, SSH/Shell, servicios activos, perfil de imagen, syslog, placas de red con velocidad de enlace, vSwitches, portgroups/VLANs, VMkernel |
| `datastores` | Capacidad, usado, libre, % de uso, **% provisionado** (sobre-asignación thin), disco físico detrás de cada datastore y VMs que lo usan |
| `vms` | Por cada VM: estado, vCPU, RAM asignada / activa / consumida, ballooning, swap, reservas, límites, shares, VMware Tools, heartbeat, sincronización horaria, NICs (e1000 vs vmxnet3), controladoras, discos (thin/thick, **usado real**), espacio libre dentro del guest |
| `snapshots` | Todos los snapshots con fecha, antigüedad, tamaño real y marca de los que superan N días |
| `performance` | CPU %, **CPU Ready %**, **Co-Stop %**, latencia de CPU, memoria activa, ballooning, swap, **latencia por disco virtual y por datastore**, IOPS. Devuelve promedio, p95 y máximo con el momento en que ocurrió |
| `historial_perf` | Las mismas métricas sobre **semanas**, filtrables por horario laboral (ver [Historial](#-historial-de-performance)) |
| `eventos` | Errores, advertencias, alarmas, tareas y logins fallidos, con la hora corregida por el desfase del reloj de ESXi |
| `top_archivos` | Los archivos más grandes de cada datastore, a qué VM pertenecen y **posibles huérfanos** (vmdk sin VM registrada) |
| `overcommit` | vCPU encendidas vs hilos físicos, RAM asignada vs física, VM más grande |
| `verificar_permisos` | Con qué usuario se conecta y si ese usuario tiene privilegios de escritura en ESXi |

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:

| Método | Para qué |
|---|---|
| `CreateContainerView` / `Destroy` | Vista temporal de la propia sesión para listar objetos |
| `PerformanceManager.QueryPerf` y afines | Métricas de performance |
| `HostDatastoreBrowser.SearchDatastoreSubFolders_Task` | Listar archivos de los datastores |
| `EventManager.QueryEvents` / `CreateCollectorForEvents` | Leer eventos (el colector es de la sesión y se destruye al terminar) |
| `AuthorizationManager.HasPrivilegeOnEntity` / `RetrieveEntityPermissions` | Verificar los permisos del propio usuario |
| `OptionManager.QueryOptions`, `HostImageConfigManager.*Get*` | Leer opciones y perfil de imagen |

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:

```json
{ "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`](https://pypi.org/project/keyring/). Las claves de licencia se muestran enmascaradas.

## 🚀 Instalación

### Requisitos

- [`uv`](https://docs.astral.sh/uv/) (se encarga de Python y de las dependencias)
- Acceso por red al puerto 443 del ESXi
- Un cliente MCP: [Claude Code](https://docs.claude.com/en/docs/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

```bash
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**

```bash
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):

```json
{
  "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

```bash
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

```bash
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

| Variable | Obligatoria | Default | Descripción |
|---|---|---|---|
| `ESXI_HOST` | ✅ | — | IP o nombre del ESXi (o del vCenter) |
| `ESXI_USER` | ✅ | — | Usuario de solo lectura |
| `ESXI_PASSWORD` | | — | Solo si no podés usar `keyring` (queda en texto plano en la config: evitalo) |
| `ESXI_PORT` | | `443` | Puerto de la API |
| `ESXI_VERIFY_SSL` | | `0` | `1` para verificar el certificado (por defecto se acepta el autofirmado de ESXi) |
| `ESXI_PERF_DB` | | `~/.esxi-readonly-mcp/perf_historial.db` | Ruta de la base SQLite del historial de performance |

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

```bash
uvx esxi-readonly-mcp --collect
```

Programalo cada hora y despué