EasyPanel MCP Server

Documentación · Inicio rápido · Reportar un problema

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) y utiliza la línea estable v2 del SDK oficial de Python. Permite a agentes de IA interactuar con una instancia de EasyPanel desde un cliente configurado, 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: Transporte local stdio, transporte remoto moderno Streamable HTTP y compatibilidad explícita con SSE.

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 e instalar el proyecto en modo editable. Esto utiliza pyproject.toml, instala las dependencias compatibles y registra el comando easypanel-mcp.

En Windows (PowerShell):

python -m venv venv
.\venv\Scripts\Activate.ps1
python -m pip install -e .

En macOS / Linux:

python3 -m venv venv
source venv/bin/activate
python -m pip install -e .

requirements.txt se mantiene disponible para instalaciones tradicionales, pero la instalación mediante pyproject.toml es la recomendada para desarrollo y para clientes MCP locales.

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

4. Verificar el arranque

Con el entorno virtual activo puedes iniciar el servidor mediante el entrypoint instalado:

easypanel-mcp

También se mantiene soportada la ejecución directa por ruta absoluta a src/server.py. El servidor resuelve sus imports relativos al repositorio, por lo que los clientes MCP no necesitan configurar PYTHONPATH ni arrancar desde la raíz del proyecto.

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 y clientes remotos (Streamable HTTP)

Para desplegar el servidor como servicio MCP remoto, inicia el transporte Streamable HTTP:

easypanel-mcp http

También puedes utilizar:

python src/server.py http

El endpoint MCP queda disponible en:

http://127.0.0.1:8080/mcp

Configura ese endpoint en un cliente compatible con MCP, por ejemplo un nodo MCP Client/MCP Client Tool de n8n. El cliente MCP se encarga de la negociación del protocolo, descubrimiento de tools y llamadas JSON-RPC.

Si necesitas mantener una integración antigua basada en Server-Sent Events, SSE continúa disponible de forma explícita:

easypanel-mcp sse

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

Seguridad

• Guarda EASYPANEL_API_KEY únicamente en variables de entorno o gestores de secretos; nunca la publiques ni la confirmes en Git.

• Usa una cuenta o token con los permisos mínimos necesarios para las tareas que vayas a ejecutar.

• Revisa las acciones destructivas propuestas por el agente antes de ejecutarlas.

• Para reportar una vulnerabilidad, consulta SECURITY.md y evita publicar credenciales o detalles sensibles en issues públicos.

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.