Coolify MCP Server

Un servidor MCP para integrarse con Coolify, la alternativa autoalojable a Netlify y Vercel.

Documentación

Coolify MCP Server

Un servidor MCP (Model Context Protocol) robusto en TypeScript para integrarse con Coolify, la alternativa autoalojable a Netlify y Vercel.

Características

Integración completa con la API de Coolify: Gestiona aplicaciones, bases de datos, servidores, proyectos y servicios
Seguridad de tipos: Soporte completo de TypeScript con definiciones de tipos exhaustivas
Protocolo MCP: Compatible con Claude y otros clientes MCP
Acceso a recursos: Expone recursos de Coolify a través de endpoints de recursos MCP
Soporte de herramientas: Conjunto completo de herramientas para operaciones de Coolify

Instalación

npm install
npm run build

Configuración

Variables de entorno

El servidor requiere variables de entorno para conectarse a tu instancia de Coolify:

export COOLIFY_API_URL="http://localhost:8000"
export COOLIFY_API_TOKEN="your-api-token-here"
export COOLIFY_TEAM_ID="optional-team-id"  # Optional

O crea un archivo .env:

COOLIFY_API_URL=http://localhost:8000
COOLIFY_API_TOKEN=your-api-token-here
COOLIFY_TEAM_ID=optional-team-id

Configuración del cliente MCP

Claude Desktop

Añade el servidor a tu archivo de configuración de Claude Desktop:

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

{
  "mcpServers": {
    "coolify": {
      "command": "node",
      "args": ["/path/to/coolify-mcp-server/dist/index.js"],
      "env": {
        "COOLIFY_API_URL": "http://localhost:8000",
        "COOLIFY_API_TOKEN": "your-api-token-here",
        "COOLIFY_TEAM_ID": "optional-team-id"
      }
    }
  }
}

Alternativa: Uso de NPX

Si publicas en npm, los usuarios pueden ejecutarlo mediante npx:

{
  "mcpServers": {
    "coolify": {
      "command": "npx",
      "args": ["@joshuarileydev/coolify-mcp-server", "--yes"],
      "env": {
        "COOLIFY_API_URL": "http://localhost:8000",
        "COOLIFY_API_TOKEN": "your-api-token-here",
        "COOLIFY_TEAM_ID": "optional-team-id"
      }
    }
  }
}

O usa el nombre del ejecutable directamente:

{
  "mcpServers": {
    "coolify": {
      "command": "npx",
      "args": ["coolify-mcp-server", "--yes"],
      "env": {
        "COOLIFY_API_URL": "http://localhost:8000",
        "COOLIFY_API_TOKEN": "your-api-token-here",
        "COOLIFY_TEAM_ID": "optional-team-id"
      }
    }
  }
}

Configuración de desarrollo

Para desarrollo, puedes usar el código fuente de TypeScript directamente:

{
  "mcpServers": {
    "coolify": {
      "command": "npx",
      "args": ["tsx", "/path/to/coolify-mcp-server/src/index.ts"],
      "env": {
        "COOLIFY_API_URL": "http://localhost:8000",
        "COOLIFY_API_TOKEN": "your-api-token-here",
        "COOLIFY_TEAM_ID": "optional-team-id"
      }
    }
  }
}

Otros clientes MCP

Para otros clientes MCP que admitan variables de entorno, asegúrate de que estén configuradas las siguientes variables:

COOLIFY_API_URL (obligatorio)
COOLIFY_API_TOKEN (obligatorio)
COOLIFY_TEAM_ID (opcional)

Ejemplo de script de shell:

#!/bin/bash
export COOLIFY_API_URL="http://localhost:8000"
export COOLIFY_API_TOKEN="your-api-token-here"
export COOLIFY_TEAM_ID="your-team-id"

node /path/to/coolify-mcp-server/dist/index.js

Herramientas disponibles

Aplicaciones

list_applications - Listar todas las aplicaciones
get_application - Obtener detalles de la aplicación
create_application - Crear nueva aplicación
start_application - Iniciar una aplicación
stop_application - Detener una aplicación
restart_application - Reiniciar una aplicación
deploy_application - Desplegar una aplicación

Bases de datos

list_databases - Listar todas las bases de datos
create_database - Crear nueva base de datos

Servidores

list_servers - Listar todos los servidores
create_server - Crear nuevo servidor
validate_server - Validar conexión del servidor

Proyectos

list_projects - Listar todos los proyectos
create_project - Crear nuevo proyecto

Servicios

list_services - Listar todos los servicios
start_service - Iniciar un servicio
stop_service - Detener un servicio

Sistema

get_version - Obtener versión de Coolify

Recursos disponibles

El servidor expone estos recursos MCP:

coolify://applications - Todas las aplicaciones
coolify://databases - Todas las bases de datos
coolify://servers - Todos los servidores
coolify://projects - Todos los proyectos
coolify://services - Todos los servicios
coolify://teams - Todos los equipos

Configuración del token de API

Inicia sesión en tu instancia de Coolify
Navega a "Keys & Tokens" > "API tokens"
Haz clic en "Crear nuevo token"
Elige los permisos adecuados:
- read-only: Solo lectura de datos
- read:sensitive: Lectura con datos sensibles
- *: Acceso completo (recomendado para el servidor MCP)
Copia el token generado

Nota de seguridad

Al usar el servidor MCP con Claude Desktop u otros clientes, tu token de API se almacenará en el archivo de configuración. Asegúrate de que este archivo tenga los permisos adecuados:

# macOS/Linux
chmod 600 ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Or set environment variables in your shell profile instead
echo 'export COOLIFY_API_TOKEN="your-token-here"' >> ~/.bashrc

Desarrollo

# Install dependencies
npm install

# Run in development mode (requires env vars)
COOLIFY_API_URL=http://localhost:8000 COOLIFY_API_TOKEN=your-token npm run dev

# Build for production
npm run build

# Run built version
npm start

# Lint code
npm run lint

# Type check
npm run typecheck

Solución de problemas

Problemas comunes

"COOLIFY_API_URL y COOLIFY_API_TOKEN son variables de entorno obligatorias"
- Asegúrate de que las variables de entorno estén configuradas antes de iniciar el servidor
- Comprueba que tu archivo .env esté en la ubicación correcta
- Verifica que los nombres de las variables estén escritos correctamente
"Ejecución de herramienta fallida: Solicitud fallida"
- Verifica que tu instancia de Coolify esté en ejecución y sea accesible
- Comprueba que la URL de la API sea correcta (incluye el protocolo: http:// o https://)
- Asegúrate de que tu token de API tenga los permisos necesarios
El servidor MCP no aparece en Claude Desktop
- Reinicia Claude Desktop después de actualizar la configuración
- Comprueba que la ruta del archivo de configuración sea correcta para tu sistema operativo
- Verifica la sintaxis JSON en el archivo de configuración

Modo de depuración

Para ver mensajes de error detallados, ejecuta el servidor con salida de depuración:

DEBUG=* node dist/index.js

Licencia

MIT