Proxmox MCP Suite

Proxmox MCP Suite

Gerencie seu cluster Proxmox VE e Backup Server pelo Claude — de forma profunda, segura e sem sobrecarregar a janela de contexto.

Início rápido · Por que esta suíte · O que há dentro · Segurança · Configuração

---

Dois servidores Model Context Protocol, empacotados como plugins do Claude Code, que transformam o Claude em um operador Proxmox capaz — 69 ferramentas entre virtualização e backup, projetadas para rodar dentro do contexto de um LLM: saída compacta, verificação de saúde em uma chamada, resultados de tarefas inline e um modelo de segurança em duas camadas com pré-visualizações de dry-run e uma trilha de auditoria à prova de adulteração.

⚡ Início rápido

Pré-requisito: Claude Code e uv (uvx). Os servidores rodam via uvx — nada para pip install manualmente.

/plugin marketplace add ahmetem/proxmox-mcp-suite
/plugin install proxmox-ve@proxmox-mcp-suite
/plugin install proxmox-backup@proxmox-mcp-suite

Exporte suas credenciais do Proxmox (veja Configuração), reinicie o Claude Code e pergunte:

"Como está o servidor? Algum armazenamento enchendo?" — uma chamada de proxmox_health_overview.

"Tire um snapshot da VM 102 como pré-upgrade e depois reinicie-a."

"Meu último backup do CT 200 está saudável?"

🎯 Por que esta suíte

A maioria dos servidores MCP do Proxmox envolve a API e entrega JSON bruto ao Claude. Este é construído para o que realmente limita um agente — contexto — e para não quebrar sua infraestrutura.

	Proxmox MCP Suite	MCP Proxmox típico
Saída	JSON compacto com limite de tamanho · health_overview em uma chamada · filtros de lista · projeção fields	Despejos completos e verbosos de objetos
Lançamento de tarefas	wait_seconds consulta a tarefa e retorna o resultado final inline	Dispara e depois faz uma segunda chamada para verificar o status
Mutações	Portão de duas camadas: confirm + i_understand_data_loss, além de pré-visualizações dry_run nas mais arriscadas	Um único sinalizador, ou nada
Auditoria	Execução de shell no host/convidado anexada a um log encadeado por hash e à prova de adulteração (proxmox_audit_verify)	Log simples, ou nenhum
Profundidade (VE)	Convidados, snapshots, backups, armazenamento, discos, LVM, ZFS completo, preparação de disco, provisionamento, análise forense de tarefas, autocorreção de backup	Apenas ciclo de vida de VM/CT
Backup (PBS)	Servidor dedicado: datastores, snapshots, GC, verificação, poda, somente leitura por padrão	Geralmente ausente
Instalação	Um marketplace, uvx — zero configuração manual de Python	Clone + venv + pip + configuração JSON

Modular por design — instale apenas Proxmox VE, apenas PBS, ou ambos.

📦 O que há dentro

proxmox-ve — 52 ferramentas

_{Repositório: homelab-proxmox-mcp}

• Convidados — listar/status, criar VM e LXC do zero, clonar, energia, redimensionar
• Snapshots — criar / reverter / excluir (com bloqueio para perda de dados)
• Backups — criar / listar / restaurar vzdump (recusa sobrescrita silenciosa)
• Armazenamento e discos — pools, detalhamento de uso, discos físicos + SMART
• LVM / ZFS — VG/thin, ZFS completo: pools, datasets, snapshots, scrub, send, propriedades, preparação de disco e provisionamento
• Execução — SSH em VM convidada, SSH no host (livre + uma variante somente leitura com lista de permissões segura para agentes), pct exec LXC, controle de serviço, cauda de log
• Análise forense e autocorreção — lista/logs de tarefas, inspeção de jobs de backup, limpeza de snapshots @vzdump obsoletos que desbloqueia backups com falha

proxmox-backup — 17 ferramentas

_{Repositório: homelab-pbs-mcp}

• Datastores e snapshots — status, uso, listar, proteger/esquecer
• Manutenção — coleta de lixo, jobs de verificação, poda (com dry-run)
• Tarefas — status e logs por UPID
• Somente leitura por padrão — ferramentas de escrita permanecem inertes até PBS_ALLOW_WRITE=true

🛡️ Modelo de segurança

Ferramentas somente leitura rodam livremente. Tudo que muda de estado exige confirm=true; qualquer coisa que destrua dados persistentes adicionalmente exige i_understand_data_loss=true — então o Claude só dispara essas ações depois que você pedir claramente.

• Pré-visualizações dry_run nas mutações de maior consequência (criar VM/CT, clonar, restaurar) retornam a chamada exata de API que fariam (com segredos mascarados), sem tocar em nada.
• Auditoria à prova de adulteração — toda execução de shell no host/convidado é anexada a um log encadeado por hash (SHA-256, ou HMAC-SHA256 com PROXMOX_AUDIT_HMAC_KEY). proxmox_audit_verify recalcula a cadeia e sinaliza qualquer linha alterada, excluída ou reordenada.
• Autenticação por token, nunca senhas de root — tokens de API são revogáveis e limitam o raio de impacto.

⚙️ Configuração

As credenciais são passadas aos servidores via variáveis de ambiente — exporte-as no shell que inicia o Claude Code (nenhum segredo é armazenado no plugin).

Proxmox VE — obrigatório: PROXMOX_HOST, PROXMOX_USER, PROXMOX_TOKEN_NAME, PROXMOX_TOKEN_VALUE. Opcional: PROXMOX_PORT, PROXMOX_VERIFY_SSL, e o PROXMOX_SSH_* das ferramentas com suporte a SSH. → lista completa no repositório do servidor.

Proxmox Backup Server — obrigatório: PBS_HOST, PBS_TOKEN_ID, PBS_TOKEN_SECRET, PBS_NODE. Opcional: PBS_VERIFY_TLS, PBS_DEFAULT_DATASTORE, e PBS_ALLOW_WRITE (controla GC/poda/esquecer). → repositório do servidor PBS.

Verifique se os servidores carregaram com /mcp.

🔧 Como funciona

Cada plugin inicia seu servidor com uvx, que busca, instala e isola automaticamente do PyPI (pve-mcp, pbs-mcp) — sem clone, sem virtualenv, sem pip install manual. uvx armazena em cache o ambiente após o primeiro início, então inícios posteriores são instantâneos. Para fixar uma versão específica, defina o args de um plugin para ex. ["pve-mcp==1.2.0"].

🔒 Notas de segurança

• Mantenha as APIs do Proxmox / PBS em uma LAN confiável ou atrás de uma VPN.
• Separe os privilégios dos tokens de API; conceda a função mais restrita que funcione.
• Não remova os bloqueios de confirm / i_understand_data_loss.

📄 Licença

GNU General Public License v3.0. Não afiliado ou endossado pela Proxmox Server Solutions GmbH. "Proxmox" é uma marca registrada de seu respectivo proprietário.