convez.ai
MCP ServerDevOps & InfraestruturaAvançado
SWORDIntel

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 GitHub
InicialPluginScore · de 0 a 100

Um 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/PveMCP

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
4

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

Python 3.11+ License: AGPL-3.0 MCP Production Ready Tools

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_exec takes a snapshot, runs your fix, validates it, and rolls back instantly if it fails.
  • 🌐 LAN Bridging: vm_expose_port dynamically 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_autodiscover maps 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

BinaryPurpose
pvemcp-serverHigh-performance MCP server (stdio transport)
vmctlHuman-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 to false to 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.

Ver o original no GitHub

Bom para

Relacionados