EasyPanel MCP Server

Servidor de Model Context Protocol (MCP) para EasyPanel. Este conector permite a clientes de inteligencia artificial y entornos de automatización gestionar infraestructura, desplegar servicios, configurar redes y monitorear recursos mediante la API tRPC de EasyPanel en lenguaje natural.

Descripción General

Este servidor implementa el estándar abierto Model Context Protocol (MCP) desarrollado por Anthropic para ofrecer herramientas de DevOps automatizadas. Permite a agentes de IA interactuar directamente con tu instancia de EasyPanel de forma local y segura, automatizando tareas complejas de administración de servidores, despliegues y diagnósticos.

Características Principales

• Gestión Completa de Servicios: Listado, inspección, creación, actualización, detención y reinicio de aplicaciones y bases de datos.

• Manejo Inteligente de Recursos: Detección automática y ruteo de namespaces tRPC según el tipo de servicio (app, postgres, redis, mysql, mongodb, mariadb).

• Auto-Scaling Automatizado: Escalado vertical de CPU y memoria basado en métricas y límites definidos.

• Análisis y Debugging: Recuperación de logs estructurados e información de despliegue para auditoría y diagnóstico de fallos en tiempo real.

• Descubrimiento de Redes: Análisis automático de topologías de comunicación interna y pública de Docker.

• Soporte Multicliente: Diseñado tanto para transporte local de flujo estándar (stdio) como para conexión remota vía Server-Sent Events (sse/http).

Related MCP server: Docker Manager MCP

Instalación y Configuración

1. Clonar el repositorio

git clone https://github.com/dannymaaz/easypanel-mcp
cd easypanel-mcp

2. Configurar el entorno virtual e instalar

Recomendamos usar un entorno virtual para aislar las dependencias:

En Windows (PowerShell):

python -m venv venv
.\venv\Scripts\Activate.ps1
pip install -r requirements.txt

En macOS / Linux:

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

3. Configurar variables de entorno

Crea un archivo .env en la raíz del proyecto basándote en el ejemplo provisto:

cp .env.example .env

Edita el archivo .env configurando los accesos a tu EasyPanel:

# URL de acceso a tu instancia (ej. https://panel.tudominio.com)
EASYPANEL_URL=https://tu-easypanel.com

# Token de API o credenciales en formato email:password
EASYPANEL_API_KEY=tu_api_key_aqui

# Parámetros adicionales
EASYPANEL_TIMEOUT=30
EASYPANEL_VERIFY_SSL=true

# Configuración del servidor MCP
MCP_HOST=127.0.0.1
MCP_PORT=8080
MCP_LOG_LEVEL=INFO

Configuración en Clientes MCP

1. Antigravity IDE

Para integrar el servidor en Antigravity, añade la ruta del script en la configuración del gestor de plugins de MCP.

Asegúrate de apuntar al ejecutable de Python de tu entorno virtual (venv) para que localice las dependencias instaladas:

{
  "mcpServers": {
    "easypanel-mcp": {
      "command": "C:\\ruta\\a\\easypanel-mcp\\venv\\Scripts\\python.exe",
      "args": ["C:\\ruta\\a\\easypanel-mcp\\src\\server.py"],
      "env": {
        "EASYPANEL_URL": "https://tu-easypanel.com",
        "EASYPANEL_API_KEY": "tu_api_key"
      }
    }
  }
}

2. Cursor / VS Code (Extensiones Cline & Roo Code)

En editores compatibles con OpenCode o extensiones de agentes inteligentes:

1. Abre el panel de configuración de la extensión (ej. en Roo Code, ve a Settings > MCP Servers).

2. Añade una nueva configuración de servidor:

   • Name: easypanel

   • Type: command

   • Command: python (o la ruta al ejecutable de tu venv)

   • Args: ["/ruta/absoluta/a/easypanel-mcp/src/server.py"]

   • Environment Variables:

     • EASYPANEL_URL: https://tu-easypanel.com

     • EASYPANEL_API_KEY: tu_api_key

3. Claude Desktop

Añade el servidor al archivo de configuración de Claude Desktop (claude_desktop_config.json):

En Windows: %APPDATA%\Claude\claude_desktop_config.json
En macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "easypanel-mcp": {
      "command": "python",
      "args": ["/ruta/absoluta/a/easypanel-mcp/src/server.py"],
      "env": {
        "EASYPANEL_URL": "https://tu-easypanel.com",
        "EASYPANEL_API_KEY": "tu_api_key"
      }
    }
  }
}

4. n8n (Integración remota vía SSE)

Si deseas desplegarlo de forma dedicada como servicio remoto, inicia el servidor en modo HTTP:

python src/server.py http

Esto levantará el servidor en http://127.0.0.1:8080 utilizando Server-Sent Events (SSE). Puedes integrarlo en nodos HTTP de n8n o sistemas externos realizando peticiones estructuradas al endpoint de herramientas:

• Endpoint: http://localhost:8080/mcp

• Formato de petición:

  {
    "method": "tools/call",
    "params": {
      "name": "list_services",
      "arguments": {
        "project_id": "mi-proyecto"
      }
    }
  }

Ejemplos Prácticos de Uso

Una vez conectado, puedes interactuar directamente con tu agente haciéndole peticiones de infraestructura basadas en la vida real:

Despliegue de Aplicaciones

Usuario: "Despliega un servicio frontend usando la imagen nginx:alpine en el proyecto principal."
IA (Interno): Invoca create_service(name="frontend", project_id="principal", image="nginx:alpine") y posteriormente deploy_service.
IA (Respuesta): "He creado y desplegado el servicio 'frontend' exitosamente en tu proyecto. Está listo para recibir configuración de dominio."

Diagnóstico de Caídas

Usuario: "¿Por qué el servicio backend está fallando?"
IA (Interno): Invoca get_service_logs(service_id="backend").
IA (Respuesta): "El servicio backend reporta un estado 'crashed' debido al siguiente error en consola: 'ConnectionRefusedError: No se pudo establecer conexión con redis-cache en el puerto 6379'. ¿Deseas que verifique si el contenedor de Redis está detenido?"

Monitoreo y Escalado

Usuario: "Verifica las estadísticas del sistema y escala el servicio backend si el uso de CPU es alto."
IA (Interno): Invoca get_system_stats() seguido de scale_service(service_id="backend", cpu=2, memory=4096).

Herramientas Disponibles

Verificación del Entorno

Para verificar la conectividad de la API y el estado de la configuración sin arrancar el servidor MCP completo, puedes ejecutar la suite de pruebas unitarias:

python -m pytest tests/test_basic.py -v

Autor

• Danny Maaz - LinkedIn • GitHub

Licencia

Este proyecto está bajo la Licencia MIT. Consulta el archivo LICENSE para más detalles.