vcenter-mcp

vcenter-mcp

Um servidor Model Context Protocol que expõe ferramentas de ciclo de vida de VMs VMware vCenter / ESXi para Claude Code e outros clientes MCP. Construído sobre pyVmomi.

O que ele faz

• Lista VMs em um datacenter vCenter (agrupadas por host) ou em um host ESXi autônomo
• Cria uma VM (inicialização pela rede primeiro; provisionamento thin ou thick; opção de virtualização aninhada para alvos ESXi)
• Liga e desliga VMs
• Exclui VMs (desliga primeiro se estiver em execução, depois remove do disco)

As consultas aceitam um nome de exibição ou um ID moref (ex.: vm-42) — o caminho moref ignora a varredura de inventário e é mais rápido em ambientes grandes.

Pré-requisitos

• Python 3.10 ou mais recente
• Um vCenter Server ou host ESXi autônomo acessível pela rede
• Uma conta vSphere com os privilégios necessários para o que você pretende fazer (somente leitura é suficiente para list_vms; criar/excluir exige os privilégios correspondentes de VM e pool de recursos)

Instalação

Instale em um virtualenv local do projeto. Usar um venv mantém vcenter-mcp e suas dependências (notavelmente pyVmomi) isolados do Python do sistema.

A partir de um clone deste repositório:

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

Para desenvolvimento (também instala pytest):

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

Ao longo deste README, os comandos usam .venv/bin/.... Você pode, em vez disso, source .venv/bin/activate uma vez por shell e remover o prefixo — mesmo resultado.

Configurar um alvo

Execute a configuração interativa usando o Python do venv:

.venv/bin/python -m vcenter_mcp setup

Você será solicitado a informar:

1. Um nome de alvo (ex.: lab-vcenter) — usado para referenciar este alvo posteriormente
2. Host ou IP do vCenter / ESXi
3. Nome de usuário e senha
4. Tipo de alvo: vcenter ou esxi
5. (Somente vCenter) Nomes do datacenter e do cluster
6. Nome do datastore
7. Um ou mais perfis de rede, cada um com um nome e um ou mais nomes de portgroup

A configuração grava um arquivo de configuração em ~/.config/vcenter-mcp/config.json (modo 0600). Execute novamente a qualquer momento para adicionar outro alvo ou atualizar um existente.

Formato do arquivo de configuração

{
  "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 }
  }
}

Um perfil de rede é uma lista de portgroups; a primeira entrada se torna a NIC de inicialização. Para adicionar seus próprios tipos de VM, adicione entradas em templates — strings vm_type passadas para create_vm são comparadas com este dicionário.

Registrar com Claude Code

Registre o servidor MCP usando o Python do venv por caminho absoluto. O Claude Code inicia o servidor em um shell novo que não herda seu venv ativado, portanto o caminho absoluto é obrigatório — apontar para um python simples aqui falhará ao 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

Ou apenas insira inline o caminho absoluto desejado:

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

As ferramentas de leitura (list_vms) são seguras para permitir sem solicitação. Adicione-as a permissions.allow em ~/.claude/settings.json:

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

As ferramentas destrutivas (create_vm, power_on_vm, power_off_vm, delete_vm) não estão intencionalmente na lista de permissões padrão — o Claude solicitará sua confirmação a cada chamada.

Ferramentas

list_vms

Lista VMs em um alvo usando uma única chamada RPC PropertyCollector (sem idas e voltas por VM).

Parâmetro	Tipo	Descrição
target	string (opcional)	Nome do alvo da configuração. Padrão: default_target.
datacenter	string (opcional)	Somente vCenter — datacenter a listar. Padrão: datacenter configurado do alvo.

Cada VM na lista retornada inclui:

Campo	Descrição
name	Nome de exibição
moref	ID de referência do objeto gerenciado (ex.: vm-42)
uuid	UUID do BIOS
power_state	poweredOn, poweredOff ou suspended
guest_id	Identificador do sistema operacional convidado (ex.: ubuntu64Guest)
guest_full_name	Nome completo do sistema operacional convidado
cpu_count	Número de vCPUs
memory_mb	Memória em MB
storage_used_bytes	Armazenamento comprometido em bytes
primary_ip	IP principal do convidado (requer VMware Tools)
nics	Lista de NICs — cada uma com mac, network e guest_ips (requer VMware Tools)
disks	Lista de discos virtuais — cada um com capacity_bytes e file (caminho relativo ao datastore)

Em caso de erro, retorna um único dicionário com uma chave error.

---

create_vm

Cria uma VM que inicializa pela rede primeiro.

Parâmetro	Tipo	Descrição
name	string	Nome de exibição da nova VM
vm_type	string	Nome do template da configuração (ex.: esxi, ubuntu, rhel)
target	string (opcional)	Nome do alvo da configuração. Padrão: default_target.
network_profile	string (opcional)	Perfil de rede nomeado da configuração do alvo (ex.: standard, secure-boot). Padrão: default_network.
cpu	int (opcional)	Substitui a contagem de CPUs do template
ram_mb	int (opcional)	Substitui a memória do template em MB
disk_gb	int (opcional)	Substitui o tamanho do disco do template em GB
disk_provisioning	string (opcional)	thin (padrão) ou thick

---

power_on_vm

Liga uma VM por nome de exibição ou ID moref (ex.: vm-42).

Parâmetro	Tipo	Descrição
name_or_id	string	Nome de exibição ou ID moref
target	string (opcional)	Nome do alvo da configuração. Padrão: default_target.

---

power_off_vm

Desliga uma VM por nome de exibição ou ID moref (ex.: vm-42).

Parâmetro	Tipo	Descrição
name_or_id	string	Nome de exibição ou ID moref
target	string (opcional)	Nome do alvo da configuração. Padrão: default_target.

---

delete_vm

Exclui permanentemente uma VM (desliga primeiro se estiver em execução, depois remove do disco).

Parâmetro	Tipo	Descrição
name_or_id	string	Nome de exibição ou ID moref
target	string (opcional)	Nome do alvo da configuração. Padrão: default_target.

Gerenciamento de conexões

vcenter-mcp mantém um ServiceInstance compartilhado por combinação de user@host durante toda a vida do processo do servidor MCP, em vez de abrir e fechar uma nova conexão a cada chamada de ferramenta.

Ciclo de vida da sessão:

• Criada na primeira chamada de ferramenta para um determinado alvo
• Reutilizada em todas as chamadas subsequentes com as mesmas credenciais
• Reconectada automaticamente se um ping de atividade (currentSession) detectar que a sessão expirou
• Desconectada explicitamente quando uma sessão é substituída (falha no ping) ou invalidada (falha NotAuthenticated / SecurityError)

Regras de compartilhamento de sessão:

Cenário	Resultado
Mesmo usuário, mesmo vCenter	Sessão compartilhada única
Usuário diferente, mesmo vCenter	Sessão separada por usuário
Mesmo usuário, vCenter diferente	Sessão separada por host

Chamadas de ferramentas concorrentes são seguras — um threading.Lock protege todas as leituras e gravações de cache.

Notas sobre TLS

vcenter-mcp conecta-se com um contexto SSL não verificado, que é o mesmo padrão usado por govc e pela maioria dos exemplos de código pyVmomi, porque vCenters de laboratório muito comumente têm certificados autoassinados. Se seu alvo usar um certificado devidamente assinado e você preferir verificação real, troque _ssl_context() em src/vcenter_mcp/client.py.

Desenvolvimento

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

Os testes são executados em Python 3.10, 3.11 e 3.12 no CI (veja .github/workflows/test.yml).

Licença

Apache-2.0