Skip to content
BranchesTags

Repository files navigation

EasyPanel MCP Server

Quality Python Version MCP Protocol EasyPanel Compatible License Platform

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.

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

Categoría Herramienta Parámetros Descripción
Servicios list_services project_id (opcional) Lista todos los servicios y sus estados.
get_service service_id (requerido) Obtiene la configuración detallada de un servicio.
create_service name, project_id, image, config Crea un nuevo servicio (soporta apps y DBs).
update_service service_id, config Modifica configuraciones de entorno, puertos y recursos.
delete_service service_id Remueve un servicio de EasyPanel.
restart_service service_id Reinicia de inmediato el contenedor de la aplicación.
get_service_logs service_id, lines (opcional) Obtiene los últimos logs de consola del contenedor.
Despliegues list_deployments project_id (opcional) Lista el historial de despliegues.
create_deployment project_id, service_id, image Lanza un nuevo despliegue actualizando la imagen.
Redes list_networks - Descubre la topología de red Docker pública/interna.
Proyectos list_projects - Lista los proyectos creados en la instancia.
create_project name, description (opcional) Crea un nuevo proyecto organizador.
Monitoreo get_system_stats - Obtiene estadísticas en tiempo real de CPU, RAM y disco.
Escalado scale_service service_id, cpu, memory Escala verticalmente los recursos asignados.
auto_scale_service service_id, cpu_threshold, memory_threshold Escala dinámicamente según la carga actual.
Seguridad list_domains - Lista los dominios asignados en la instancia.
get_public_key - Obtiene la clave SSH pública para despliegues Git.

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

Licencia

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

About

MCP server that bridges AI assistants with EasyPanel. Control your infrastructure through natural language – deploy services, manage deployments, networks, and projects via Claude Desktop, n8n, or custom AI agents.

dannymaaz.github.io/easypanel-mcp/

Topics

ai-agentsautomationclaudedeploymentdevopsdockereasypanelinfrastructuremcpmodel-context-protocoln8npythonserver-management

Resources

Readme
License

Security policy

Security policy
Activity

Stars

4 stars

Watchers

0 watching

Forks

2 forks
Report repository

Releases

Packages

Contributors

Languages