🚀 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)

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
Instalar dependencias:
# Install with development dependencies uv pip install -e ".[dev]"
Crear configuración:
# Create config directory and copy template mkdir -p proxmox-config cp config/config.example.json proxmox-config/config.json
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

Compruebe el entorno de Python:
python -c "import proxmox_mcp; print('Installation OK')"
Ejecutar las pruebas:
pytest
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

Inicie sesión en su interfaz web de Proxmox
Vaya a Centro de datos -> Permisos -> Tokens de API
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:

# Activate virtual environment first
source .venv/bin/activate  # Linux/macOS
# OR
.\.venv\Scripts\Activate.ps1  # Windows

# Run the server
python -m proxmox_mcp.server

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 ):

{
    "mcpServers": {
        "github.com/canvrno/ProxmoxMCP": {
            "command": "/absolute/path/to/ProxmoxMCP/.venv/bin/python",
            "args": ["-m", "proxmox_mcp.server"],
            "cwd": "/absolute/path/to/ProxmoxMCP",
            "env": {
                "PYTHONPATH": "/absolute/path/to/ProxmoxMCP/src",
                "PROXMOX_MCP_CONFIG": "/absolute/path/to/ProxmoxMCP/proxmox-config/config.json",
                "PROXMOX_HOST": "your-proxmox-host",
                "PROXMOX_USER": "username@pve",
                "PROXMOX_TOKEN_NAME": "token-name",
                "PROXMOX_TOKEN_VALUE": "token-value",
                "PROXMOX_PORT": "8006",
                "PROXMOX_VERIFY_SSL": "false",
                "PROXMOX_SERVICE": "PVE",
                "LOG_LEVEL": "DEBUG"
            },
            "disabled": false,
            "autoApprove": []
        }
    }
}

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

# This will print the MCP settings with your absolute paths filled in
python -c "import os; print(f'''{{
    \"mcpServers\": {{
        \"github.com/canvrno/ProxmoxMCP\": {{
            \"command\": \"{os.path.abspath('.venv/bin/python')}\",
            \"args\": [\"-m\", \"proxmox_mcp.server\"],
            \"cwd\": \"{os.getcwd()}\",
            \"env\": {{
                \"PYTHONPATH\": \"{os.path.abspath('src')}\",
                \"PROXMOX_MCP_CONFIG\": \"{os.path.abspath('proxmox-config/config.json')}\",
                ...
            }}
        }}
    }}
}}''')"

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

proxmox-mcp/
├── src/
│   └── proxmox_mcp/
│       ├── server.py          # Main MCP server implementation
│       ├── config/            # Configuration handling
│       ├── core/              # Core functionality
│       ├── formatting/        # Output formatting and themes
│       ├── tools/             # Tool implementations
│       │   └── console/       # VM console operations
│       └── utils/             # Utilities (auth, logging)
├── tests/                     # Test suite
├── proxmox-config/
│   └── config.example.json    # Configuration template
├── pyproject.toml            # Project metadata and dependencies
└── LICENSE                   # MIT License

📄 Licencia

Licencia MIT

Proxmox MCP Server

Integrations