vcenter-mcp

vcenter-mcp

Un servidor de Model Context Protocol que expone herramientas del ciclo de vida de máquinas virtuales de VMware vCenter / ESXi a Claude Code y otros clientes MCP. Construido sobre pyVmomi.

Qué hace

• Lista máquinas virtuales en un datacenter de vCenter (agrupadas por host) o en un host ESXi independiente
• Crea una máquina virtual (arranque por red primero; aprovisionamiento thin o thick; opción de virtualización anidada para destinos ESXi)
• Enciende y apaga máquinas virtuales
• Elimina máquinas virtuales (las apaga primero si están en ejecución, luego las destruye del disco)

Las búsquedas aceptan un nombre visible o un ID moref (p. ej. vm-42) — la ruta moref omite el escaneo de inventario y es más rápida en entornos grandes.

Requisitos previos

• Python 3.10 o más reciente
• Un vCenter Server o host ESXi independiente al que puedas acceder por red
• Una cuenta de vSphere con los privilegios necesarios para lo que planees hacer (solo lectura es suficiente para list_vms; crear / eliminar requieren los privilegios correspondientes de VM y pool de recursos)

Instalación

Instala en un virtualenv local del proyecto. Usar un venv mantiene vcenter-mcp y sus dependencias (notablemente pyVmomi) aislados de tu Python del sistema.

Desde un clon de este repositorio:

python3 -m venv .venv
.venv/bin/pip install --upgrade pip
.venv/bin/pip install -e .

Para desarrollo (también instala pytest):

.venv/bin/pip install -e ".[dev]"

A lo largo de este README, los comandos usan .venv/bin/.... Puedes en su lugar source .venv/bin/activate una vez por shell y omitir el prefijo — mismo resultado.

Configurar un destino

Ejecuta la configuración interactiva usando el Python del venv:

.venv/bin/python -m vcenter_mcp setup

Se te pedirá:

1. Un nombre de destino (p. ej. lab-vcenter) — usado para referirse a este destino más adelante
2. Host o IP del vCenter / ESXi
3. Nombre de usuario y contraseña
4. Tipo de destino: vcenter o esxi
5. (Solo vCenter) Nombres del datacenter y del clúster
6. Nombre del datastore
7. Uno o más perfiles de red, cada uno con un nombre más uno o más nombres de portgroup

La configuración escribe un archivo de configuración en ~/.config/vcenter-mcp/config.json (modo 0600). Vuelve a ejecutarlo en cualquier momento para añadir otro destino o actualizar uno existente.

Forma del archivo de configuración

{
  "default_target": "lab-vcenter",
  "targets": {
    "lab-vcenter": {
      "host": "vcenter.lab.example.com",
      "user": "admin@vsphere.local",
      "password": "...",
      "type": "vcenter",
      "datacenter": "Lab DC",
      "cluster": "Lab Cluster",
      "datastore": "datastore1",
      "networks": {
        "standard": ["VM Network"],
        "secure-boot": ["pg-secure-1", "pg-secure-2"]
      },
      "default_network": "standard"
    }
  },
  "templates": {
    "esxi":   { "cpu": 4, "ram_mb": 16384, "disk_gb": 100, "disk_provisioning": "thin", "guest_id": "vmkernel7Guest", "vhv": true },
    "ubuntu": { "cpu": 2, "ram_mb": 4096,  "disk_gb": 40,  "disk_provisioning": "thin", "guest_id": "ubuntu64Guest",  "vhv": false },
    "rhel":   { "cpu": 2, "ram_mb": 4096,  "disk_gb": 40,  "disk_provisioning": "thin", "guest_id": "rhel9_64Guest",  "vhv": false }
  }
}

Un perfil de red es una lista de portgroups; la primera entrada se convierte en la NIC de arranque. Para añadir tus propios tipos de VM, añade entradas a templates — las cadenas vm_type pasadas a create_vm se comparan con este diccionario.

Registrar con Claude Code

Registra el servidor MCP usando el Python del venv por ruta absoluta. Claude Code lanza el servidor en un shell nuevo que no hereda tu venv activado, por lo que la ruta absoluta es obligatoria — apuntar a un python simple aquí fallará al importar vcenter_mcp.

VCENTER_MCP_DIR="$(pwd)"   # run this from the repo root, after install
claude mcp add --scope user vcenter -- "$VCENTER_MCP_DIR/.venv/bin/python" -m vcenter_mcp

O simplemente incluye la ruta absoluta que quieras:

claude mcp add --scope user vcenter -- /absolute/path/to/vcenter-mcp/.venv/bin/python -m vcenter_mcp

Las herramientas de lectura (list_vms) son seguras de permitir sin aviso. Añádelas a permissions.allow en ~/.claude/settings.json:

{
  "permissions": {
    "allow": [
      "mcp__vcenter__list_vms"
    ]
  }
}

Las herramientas destructivas (create_vm, power_on_vm, power_off_vm, delete_vm) no están intencionalmente en la lista de permitidos por defecto — Claude te pedirá confirmación en cada llamada.

Herramientas

list_vms

Lista máquinas virtuales en un destino usando una única llamada RPC de PropertyCollector (sin viajes de ida y vuelta por VM).

Parámetro	Tipo	Descripción
target	string (opcional)	Nombre del destino desde la configuración. Por defecto default_target.
datacenter	string (opcional)	Solo vCenter — datacenter a listar. Por defecto el datacenter configurado del destino.

Cada VM en la lista devuelta incluye:

Campo	Descripción
name	Nombre visible
moref	ID de referencia del objeto gestionado (p. ej. vm-42)
uuid	UUID del BIOS
power_state	poweredOn, poweredOff o suspended
guest_id	Identificador del sistema operativo invitado (p. ej. ubuntu64Guest)
guest_full_name	Nombre completo del sistema operativo invitado
cpu_count	Número de vCPUs
memory_mb	Memoria en MB
storage_used_bytes	Almacenamiento comprometido en bytes
primary_ip	IP principal del invitado (requiere VMware Tools)
nics	Lista de NICs — cada una con mac, network y guest_ips (requiere VMware Tools)
disks	Lista de discos virtuales — cada uno con capacity_bytes y file (ruta relativa al datastore)

En caso de error, devuelve un único diccionario con una clave error.

---

create_vm

Crea una máquina virtual que arranca por red primero.

Parámetro	Tipo	Descripción
name	string	Nombre visible para la nueva VM
vm_type	string	Nombre de plantilla desde la configuración (p. ej. esxi, ubuntu, rhel)
target	string (opcional)	Nombre del destino desde la configuración. Por defecto default_target.
network_profile	string (opcional)	Perfil de red con nombre desde la configuración del destino (p. ej. standard, secure-boot). Por defecto default_network.
cpu	int (opcional)	Sobrescribir el recuento de CPU de la plantilla
ram_mb	int (opcional)	Sobrescribir la memoria de la plantilla en MB
disk_gb	int (opcional)	Sobrescribir el tamaño de disco de la plantilla en GB
disk_provisioning	string (opcional)	thin (por defecto) o thick

---

power_on_vm

Enciende una VM por nombre visible o ID moref (p. ej. vm-42).

Parámetro	Tipo	Descripción
name_or_id	string	Nombre visible o ID moref
target	string (opcional)	Nombre del destino desde la configuración. Por defecto default_target.

---

power_off_vm

Apaga forzosamente una VM por nombre visible o ID moref (p. ej. vm-42).

Parámetro	Tipo	Descripción
name_or_id	string	Nombre visible o ID moref
target	string (opcional)	Nombre del destino desde la configuración. Por defecto default_target.

---

delete_vm

Elimina permanentemente una VM (la apaga primero si está en ejecución, luego la destruye del disco).

Parámetro	Tipo	Descripción
name_or_id	string	Nombre visible o ID moref
target	string (opcional)	Nombre del destino desde la configuración. Por defecto default_target.

Gestión de conexiones

vcenter-mcp mantiene un ServiceInstance compartido por combinación de user@host durante toda la vida del proceso del servidor MCP en lugar de abrir y cerrar una nueva conexión en cada llamada de herramienta.

Ciclo de vida de la sesión:

• Creada en la primera llamada de herramienta para un destino dado
• Reutilizada en todas las llamadas posteriores con las mismas credenciales
• Reconectada automáticamente si un ping de actividad (currentSession) detecta que la sesión ha expirado
• Desconectada explícitamente cuando una sesión se reemplaza (fallo de ping) o se invalida (fallo de NotAuthenticated / SecurityError)

Reglas de compartición de sesiones:

Escenario	Resultado
Mismo usuario, mismo vCenter	Sesión compartida única
Usuario diferente, mismo vCenter	Sesión separada por usuario
Mismo usuario, vCenter diferente	Sesión separada por host

Las llamadas de herramienta concurrentes son seguras — un threading.Lock protege todas las lecturas y escrituras de caché.

Notas sobre TLS

vcenter-mcp se conecta con un contexto SSL no verificado, que es el mismo valor predeterminado que usan govc y la mayoría del código de ejemplo de pyVmomi porque los vCenters de laboratorio muy comúnmente tienen certificados autofirmados. Si tu destino usa un certificado firmado correctamente y prefieres verificación real, cambia _ssl_context() en src/vcenter_mcp/client.py.

Desarrollo

python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest

Las pruebas se ejecutan en Python 3.10, 3.11 y 3.12 en CI (ver .github/workflows/test.yml).

Licencia

Apache-2.0