🚀 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:
- 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
- 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 virtualvmid (cadena, obligatoria): ID de la máquina virtualcommand (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