PveMCP - Plano de Controle Proxmox para Agentes IA
SWORDIntel/PveMCP
Orquestrador Proxmox com 67 ferramentas para automação segura de infraestrutura por agentes IA
Ver no GitHubUm servidor MCP production-grade que oferece controle completo sobre infraestrutura Proxmox, permitindo que agentes IA (como Claude) gerenciem VMs, containers e hosts remotos de forma autônoma e segura. Inclui 67 ferramentas para ciclo de vida de VMs, inspeção em tempo real, execução transacional com snapshots automáticos, gerenciamento de credenciais criptografadas e orquestração de Docker.
Instalação
npx convez-ai SWORDIntel/PveMCP1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Debugar e corrigir VMs com reversão automática via snapshots
- Descobrir automaticamente serviços e arquitetura de VMs inteiras
- Gerenciar fluxos de trabalho complexos de infraestrutura com IA
- Monitorar telemetria em tempo real e logs de múltiplas VMs
- Provisionar e orquestrar stacks Docker completos programaticamente
Veredito

Solução robusta e madura para automação de infraestrutura Proxmox via agentes IA. Destaca-se pela execução transacional segura com snapshots, criptografia de credenciais AES-256-GCM e cobertura abrangente de operações (67 ferramentas). Ideal para equipes que já usam Proxmox e buscam autonomia total na orquestração.
README
A tradução para o português deste README ainda está na fila.
🌌 PveMCP
The Proxmox VM Control Plane for AI Agents
A production-grade Proxmox orchestrator that gives your AI agent "God-mode" over your cluster and remote SSH hosts.
Tool Reference • Workflow Framework • Installation • Security
🚀 Showcase
PveMCP empowers your AI assistant (Claude, Cursor, Gemini) to handle complex infrastructure tasks autonomously and safely.
- 🛡️ Fearless Debugging:
vm_transactional_exectakes a snapshot, runs your fix, validates it, and rolls back instantly if it fails. - 🌐 LAN Bridging:
vm_expose_portdynamically maps internal VM services to random high ports on your host's LAN IP for instant access. - 🔐 Encrypted Secrets: Store private SSH keys and credentials in a unified memory store, encrypted at rest with AES-256-GCM.
- 📊 Live Observability: Stream remote logs in real-time and view a live Markdown "HUD" dashboard of your entire fleet.
- ✨ Zero-Config Onboarding:
vm_autodiscovermaps an entire VM's services, containers, and OS architecture in seconds.
🛠️ Tooling Overview
PveMCP's 67 tools are organized into functional categories to empower autonomous operation:
- ⚡ VM Lifecycle: Power states, cloning, migration, vzdump backups, and hardware configuration.
- 🔍 Guest Inspection: Real-time process monitoring, CPU/RAM telemetry, and disk health analysis.
- 📜 Guest Logs: Stream systemd journals, kernel ring buffers (dmesg), and specific log files.
- 📂 File Operations: High-performance FTP-bridge transfers, archive management, and config writing.
- 🛰️ Federation: SSH gateway for non-PVE hosts with persistent encrypted credential management.
- 🏗️ Docker & Compose: Deploy complete stacks in one shot and manage container lifecycles.
- 🧠 VM Memory: A unified, persistent JSON knowledge base for all VM-specific quirks and secrets.
- 🧪 Network Diagnostics: In-guest HTTP requests (
curl), traceroutes, DNS checks, and port auditing. - 🤖 Automation: One-shot autodiscovery and baseline drift detection for self-healing infrastructure.
🏗️ Key Components
| Binary | Purpose |
|---|---|
pvemcp-server | High-performance MCP server (stdio transport) |
vmctl | Human-facing CLI for scripting and manual cluster control |
🛠️ Advanced Configuration
Sudo & Permissions
The vmctl CLI and pvemcp-server default to using sudo for host-side Proxmox commands to ensure access to the cluster filesystem (pmxcfs).
- Environment Variables:
PVEMCP_USE_SUDO: Set tofalseto disable automatic sudo prefixing (default:true).PVEMCP_AUDIT_LOG: Path to the audit log file.PUSHBULLET_API_KEY: Your Pushbullet Access Token for notifications.
Error Diagnostics
PveMCP includes built-in diagnostics for common Proxmox cluster issues. If a command fails with ipcc_send_rec or ACL errors, the tool output will include a [DIAGNOSTIC] block explaining potential causes like lost cluster quorum or missing sudo permissions.
⚡ Quick Start
1. Installation
# Recommended: Install using uv
uv sync
uv run pvemcp-server
# Or use the one-shot installer to wire into your clients
bash scripts/install-pvemcp.sh --client both
2. First Run Sequence
uv run vmctl autodiscover 100 # map everything -> save to memory
uv run vmctl memory get 100 # verify saved context
uv run vmctl drift-check 100 # detect unauthorized changes later
🔒 Security & Safety
PveMCP is built for secure, single-operator environments:
- Fail-Closed: Every command must be explicitly permitted by policy.
- Redaction: Secrets and keys are stripped from outputs before the AI sees them.
- Audit: Every action is logged to an append-only JSON file for full accountability.
- Encryption: Sensitive memory fields are AES-256 encrypted using a machine-local secret.
- Notifications: Pushbullet integration for pipeline stages and AI alerts (
PUSHBULLET_API_KEY).
⚖️ License
This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).
⚠️ Commercial Use Warning: The AGPL-3.0 is a highly restrictive copyleft license. If you modify this software or use it over a network as part of a commercial service, you must open-source your entire service under the same license.
- Home & Personal Use: 100% Free and Open Source.
- Commercial / Enterprise Use: If the AGPL-3.0 is too harsh for your environment, please email me to discuss a commercial license.
See the LICENSE file for full details. full details.