🚀 Proxmox Manager - Servidor MCP de Proxmox

Un servidor de Protocolo de contexto de modelo (MCP) basado en Python para interactuar con hipervisores Proxmox, proporcionando una interfaz limpia para administrar nodos, máquinas virtuales y contenedores.

🏗️ Construido con

• Cline - Agente de codificación autónomo: vaya más rápido con Cline.

• Proxmoxer : contenedor de Python para la API de Proxmox

• SDK de MCP - SDK de protocolo de contexto de modelo

• Pydantic - Validación de datos mediante anotaciones de tipo de Python

✨ Características

• 🤖 Integración completa con Cline

• 🛠️ Creado con el SDK oficial de MCP

• Autenticación segura basada en tokens con Proxmox

• 🖥️ Herramientas para gestionar nodos y máquinas virtuales

• 💻 Ejecución de comandos de la consola de VM

• 📝 Sistema de registro configurable

• ✅ Implementación de tipos seguros con Pydantic

• 🎨 Formato de salida enriquecido con temas personalizables

https://github.com/user-attachments/assets/1b5f42f7-85d5-4918-aca4-d38413b0e82b

📦 Instalación

Prerrequisitos

• Gestor de paquetes UV (recomendado)

• Python 3.10 o superior

• Git

• Acceso a un servidor Proxmox con credenciales de token API

Antes de comenzar, asegúrese de tener:

• [ ] Nombre de host o IP del servidor Proxmox

• [ ] Token API de Proxmox (ver Configuración del token API )

• [ ] UV instalado ( pip install uv )

Opción 1: Instalación rápida (recomendada)

1. Clonar y configurar el entorno:

   # Clone repository cd ~/Documents/Cline/MCP # For Cline users # OR cd your/preferred/directory # For manual installation git clone https://github.com/canvrno/ProxmoxMCP.git cd ProxmoxMCP # Create and activate virtual environment uv venv source .venv/bin/activate # Linux/macOS # OR .\.venv\Scripts\Activate.ps1 # Windows

2. Instalar dependencias:

   # Install with development dependencies uv pip install -e ".[dev]"

3. Crear configuración:

   # Create config directory and copy template mkdir -p proxmox-config cp config/config.example.json proxmox-config/config.json

4. Editar proxmox-config/config.json :

   { "proxmox": { "host": "PROXMOX_HOST", # Required: Your Proxmox server address "port": 8006, # Optional: Default is 8006 "verify_ssl": false, # Optional: Set false for self-signed certs "service": "PVE" # Optional: Default is PVE }, "auth": { "user": "USER@pve", # Required: Your Proxmox username "token_name": "TOKEN_NAME", # Required: API token ID "token_value": "TOKEN_VALUE" # Required: API token value }, "logging": { "level": "INFO", # Optional: DEBUG for more detail "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s", "file": "proxmox_mcp.log" # Optional: Log to file } }

Verificación de la instalación

1. Compruebe el entorno de Python:

   python -c "import proxmox_mcp; print('Installation OK')"

2. Ejecutar las pruebas:

   pytest

3. Verificar configuración:

   # Linux/macOS PROXMOX_MCP_CONFIG="proxmox-config/config.json" python -m proxmox_mcp.server # Windows (PowerShell) $env:PROXMOX_MCP_CONFIG="proxmox-config\config.json"; python -m proxmox_mcp.server

   Deberías ver:

   • Una conexión exitosa a su servidor Proxmox

   • O un error de conexión (si los detalles de Proxmox son incorrectos)

⚙️ Configuración

Configuración del token API de Proxmox

1. Inicie sesión en su interfaz web de Proxmox

2. Vaya a Centro de datos -> Permisos -> Tokens de API

3. Crear un nuevo token de API:

   • Seleccione un usuario (por ejemplo, root@pam)

   • Introduzca un ID de token (por ejemplo, "mcp-token")

   • Desmarque "Separación de privilegios" si desea acceso completo

   • Guarde y copie tanto el ID del token como el secreto

🚀 Ejecución del servidor

Modo de desarrollo

Para pruebas y desarrollo:

Integración de escritorio de Cline

Para los usuarios de Cline, agregue esta configuración a su archivo de configuración de MCP (normalmente en ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json ):

Para ayudar a generar las rutas correctas, puede utilizar este comando:

Importante:

• Todas las rutas deben ser absolutas

• El intérprete de Python debe ser de su entorno virtual

• PYTHONPATH debe apuntar al directorio src

• Reiniciar VSCode después de actualizar la configuración de MCP

🔧 Herramientas disponibles

El servidor proporciona las siguientes herramientas MCP para interactuar con Proxmox:

obtener_nodos

Enumera todos los nodos del clúster Proxmox.

• Parámetros: Ninguno

• Ejemplo de respuesta:

  🖥️ Proxmox Nodes 🖥️ pve-compute-01 • Status: ONLINE • Uptime: ⏳ 156d 12h • CPU Cores: 64 • Memory: 186.5 GB / 512.0 GB (36.4%) 🖥️ pve-compute-02 • Status: ONLINE • Uptime: ⏳ 156d 11h • CPU Cores: 64 • Memory: 201.3 GB / 512.0 GB (39.3%)

obtener_estado_del_nodo

Obtenga el estado detallado de un nodo específico.

• Parámetros:

  • node (cadena, obligatorio): Nombre del nodo

• Ejemplo de respuesta:

  🖥️ Node: pve-compute-01 • Status: ONLINE • Uptime: ⏳ 156d 12h • CPU Usage: 42.3% • CPU Cores: 64 (AMD EPYC 7763) • Memory: 186.5 GB / 512.0 GB (36.4%) • Network: ⬆️ 12.8 GB/s ⬇️ 9.2 GB/s • Temperature: 38°C

obtener_vms

Enumere todas las máquinas virtuales del clúster.

• Parámetros: Ninguno

• Ejemplo de respuesta:

  🗃️ Virtual Machines 🗃️ prod-db-master (ID: 100) • Status: RUNNING • Node: pve-compute-01 • CPU Cores: 16 • Memory: 92.3 GB / 128.0 GB (72.1%) 🗃️ prod-web-01 (ID: 102) • Status: RUNNING • Node: pve-compute-01 • CPU Cores: 8 • Memory: 12.8 GB / 32.0 GB (40.0%)

obtener_almacenamiento

Enumere el almacenamiento disponible.

• Parámetros: Ninguno

• Ejemplo de respuesta:

  💾 Storage Pools 💾 ceph-prod • Status: ONLINE • Type: rbd • Usage: 12.8 TB / 20.0 TB (64.0%) • IOPS: ⬆️ 15.2k ⬇️ 12.8k 💾 local-zfs • Status: ONLINE • Type: zfspool • Usage: 3.2 TB / 8.0 TB (40.0%) • IOPS: ⬆️ 42.8k ⬇️ 35.6k

obtener_estado_del_clúster

Obtener el estado general del clúster.

• Parámetros: Ninguno

• Ejemplo de respuesta:

  ⚙️ Proxmox Cluster • Name: enterprise-cloud • Status: HEALTHY • Quorum: OK • Nodes: 4 ONLINE • Version: 8.1.3 • HA Status: ACTIVE • Resources: - Total CPU Cores: 192 - Total Memory: 1536 GB - Total Storage: 70 TB • Workload: - Running VMs: 7 - Total VMs: 8 - Average CPU Usage: 38.6% - Average Memory Usage: 42.8%

ejecutar_comando_vm

Ejecute un comando en la consola de una máquina virtual mediante el agente invitado QEMU.

• Parámetros:

  • node (cadena, obligatorio): nombre del nodo donde se ejecuta la máquina virtual

  • vmid (cadena, obligatoria): ID de la máquina virtual

  • command (cadena, obligatorio): Comando a ejecutar

• Ejemplo de respuesta:

  🔧 Console Command Result • Status: SUCCESS • Command: systemctl status nginx • Node: pve-compute-01 • VM: prod-web-01 (ID: 102) Output: ● nginx.service - A high performance web server and a reverse proxy server Loaded: loaded (/lib/systemd/system/nginx.service; enabled; vendor preset: enabled) Active: active (running) since Tue 2025-02-18 15:23:45 UTC; 2 months 3 days ago

• Requisitos:

  • La máquina virtual debe estar ejecutándose

  • El agente invitado de QEMU debe estar instalado y ejecutándose en la máquina virtual

  • Los permisos de ejecución de comandos deben estar habilitados en el Agente Invitado

• Manejo de errores:

  • Devuelve un error si la máquina virtual no se está ejecutando

  • Devuelve un error si no se encuentra la máquina virtual

  • Devuelve un error si falla la ejecución del comando

  • Incluye la salida del comando incluso si el comando devuelve un código de salida distinto de cero

👨‍💻 Desarrollo

Después de activar su entorno virtual:

• Ejecutar pruebas: pytest

• Código de formato: black .

• Comprobación de tipos: mypy .

• Pelusa: ruff .

📁 Estructura del proyecto

📄 Licencia

Licencia MIT