Supabase Coolify MCP Server

Servidor MCP completo para gestionar Supabase autoalojado en Coolify con soporte completo para despliegue, migraciones, edge functions y reversión.

GitHub
3
Prueba este MCPPatrocinado

Documentación

Supabase Coolify MCP Server

npm version npm downloads License: MIT TypeScript Node Version

⚡ Instalación con un clic

Instala directamente en tu herramienta de codificación con IA favorita:

Install in VS Code Install in VS Code Insiders Install in Cursor

Claude Code:

claude mcp add supabase-coolify -- npx -y supabase-coolify-mcp-server

Nota: Después de la instalación, deberás configurar las variables de entorno requeridas. Consulta Configuración a continuación.

Un servidor MCP (Model Context Protocol) completo en TypeScript para gestionar Supabase autoalojado en Coolify. Este servidor permite a los agentes de IA implementar migraciones, publicar edge functions, configurar servicios y gestionar implementaciones de Supabase con facilidad.

📦 Paquete NPM • 📚 Documentación • 🚀 Inicio rápido

🚀 Características

Gestión de Supabase

  • Migraciones de base de datos: Implementa, rastrea, revierte y gestiona migraciones de base de datos
  • Reversión de migraciones: Revierte migraciones de forma segura con soporte de SQL down
  • Integración con Supabase CLI: Integración completa de CLI para desarrollo local e implementación
  • Edge Functions: Implementa, invoca, monitorea y elimina edge functions
  • Gestión de almacenamiento: Crea y gestiona buckets de almacenamiento
  • Configuración de autenticación: Configura proveedores y ajustes de autenticación
  • Configuración en tiempo real: Gestiona los ajustes del servicio en tiempo real
  • Monitoreo de estado: Verifica el estado de todos los servicios de Supabase
  • Generación de tipos: Genera tipos TypeScript a partir del esquema de la base de datos

Características de producción

  • Validación de entrada: Validación basada en Zod para todas las entradas de herramientas
  • Verificaciones de estado: Comprobaciones automáticas de inicio y herramienta de verificación
  • Manejo de errores: Mensajes de error completos con sugerencias de solución de problemas
  • Seguridad de tipos: Soporte completo de TypeScript en todo el sistema

Integración con Coolify

  • Gestión de aplicaciones: Lista, implementa, inicia, detiene y reinicia aplicaciones
  • Gestión de servicios: Controla los servicios de Coolify
  • Gestión de bases de datos: Gestiona bases de datos alojadas en Coolify
  • Variables de entorno: Actualiza la configuración de la aplicación de forma segura
  • Registros: Accede a los registros de la aplicación para depuración

Automatización de implementación

  • Implementación con un clic: Implementa instancias completas de Supabase en Coolify
  • Gestión de configuración: Actualiza los ajustes de implementación dinámicamente
  • Monitoreo de estado: Rastrea el estado y la salud de la implementación

📋 Requisitos previos

  • Node.js >= 18.0.0
  • Una instancia de Coolify (autoalojada o en la nube)
  • Token de API de Coolify con permisos adecuados
  • Una instancia de Supabase autoalojada (o lista para implementar una)

🔧 Instalación

Método 1: NPM (Recomendado)

Instala globalmente vía NPM:

npm install -g supabase-coolify-mcp-server

O úsalo directamente con npx (sin necesidad de instalación):

npx supabase-coolify-mcp-server

Paquete: https://www.npmjs.com/package/supabase-coolify-mcp-server

Método 2: Desde el código fuente

Clona y compila desde GitHub:

git clone https://github.com/dj-pearson/supabase-coolify-mcp-server.git
cd supabase-coolify-mcp-server
npm install
npm run build

⚙️ Configuración

Variables de entorno

Crea un archivo .env o establece las siguientes variables de entorno:

# Required: Coolify Configuration
COOLIFY_API_URL=http://localhost:8000
COOLIFY_API_TOKEN=your-coolify-api-token-here

# Required: Supabase Configuration
SUPABASE_URL=https://your-supabase-instance.example.com
SUPABASE_SERVICE_ROLE_KEY=your-supabase-service-role-key

# Optional: Coolify Team
COOLIFY_TEAM_ID=optional-team-id

# Optional: Supabase Additional Config
SUPABASE_ANON_KEY=your-supabase-anon-key
SUPABASE_PROJECT_ID=your-project-id
SUPABASE_PROJECT_REF=your-project-ref
SUPABASE_FUNCTIONS_URL=https://your-supabase-instance.example.com/functions/v1

# Optional: Direct Database Access
SUPABASE_DB_HOST=localhost
SUPABASE_DB_PORT=5432
SUPABASE_DB_NAME=postgres
SUPABASE_DB_USER=postgres
SUPABASE_DB_PASSWORD=your-db-password

Obtención de tokens de API

Token de API de Coolify

  1. Inicia sesión en tu instancia de Coolify
  2. Navega a "Keys & Tokens" > "API tokens"
  3. Haz clic en "Create New Token"
  4. Selecciona permisos (recomendado: * para acceso completo)
  5. Copia el token generado

Clave de rol de servicio de Supabase

Para Supabase autoalojado:

  1. Inicia sesión en tu panel de Supabase
  2. Ve a Settings > API
  3. Copia la clave service_role (¡mantenla segura!)

O desde las variables de entorno de tu implementación de Supabase:

echo $SERVICE_ROLE_KEY

🎯 Uso

⚠️ IMPORTANTE: Variables de entorno requeridas

El servidor MCP requiere variables de entorno para conectarse a Coolify y Supabase.

Configuración recomendada (funciona para todos):

Añade variables de entorno directamente a tu configuración de MCP:

{
  "mcpServers": {
    "supabase-coolify": {
      "command": "npx",
      "args": ["-y", "supabase-coolify-mcp-server"],
      "env": {
        "COOLIFY_API_URL": "http://your-coolify-url:8000",
        "COOLIFY_API_TOKEN": "your-actual-token",
        "SUPABASE_URL": "https://your-supabase-url.com",
        "SUPABASE_SERVICE_ROLE_KEY": "your-actual-service-role-key"
      }
    }
  }
}

¡Reemplaza los valores de marcador de posición con tus credenciales reales!

📖 Opciones de configuración

El servidor admite tres métodos para proporcionar variables de entorno (en orden de prioridad):

  1. Sección env de configuración MCP ⭐ RECOMENDADO - Funciona para todos, autónomo
  2. Variables de entorno del sistema - Para usuarios avanzados que quieren credenciales fuera de la configuración
  3. Archivo .env con script contenedor - Solo para desarrollo local (no escalable)

Para instrucciones detalladas de configuración de cada método, consulta: MCP_CONFIGURATION.md

Error común: ❌ Dejar valores de marcador de posición como https://your-supabase-instance.example.com
Solución: ✅ ¡Reemplaza TODOS los marcadores de posición con tus URLs y credenciales reales!

Con Claude Desktop

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

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

Usando NPX (Recomendado - Siempre la última versión)

{
  "mcpServers": {
    "supabase-coolify": {
      "command": "npx",
      "args": ["-y", "supabase-coolify-mcp-server"],
      "env": {
        "COOLIFY_API_URL": "http://localhost:8000",
        "COOLIFY_API_TOKEN": "your-coolify-api-token",
        "SUPABASE_URL": "https://your-supabase-instance.example.com",
        "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key"
      }
    }
  }
}

Usando instalación global

Primero instala globalmente:

npm install -g supabase-coolify-mcp-server

Luego configura:

{
  "mcpServers": {
    "supabase-coolify": {
      "command": "supabase-coolify-mcp",
      "env": {
        "COOLIFY_API_URL": "http://localhost:8000",
        "COOLIFY_API_TOKEN": "your-coolify-api-token",
        "SUPABASE_URL": "https://your-supabase-instance.example.com",
        "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key"
      }
    }
  }
}

Modo de desarrollo

# Using environment variables
export COOLIFY_API_URL="http://localhost:8000"
export COOLIFY_API_TOKEN="your-token"
export SUPABASE_URL="https://your-instance.example.com"
export SUPABASE_SERVICE_ROLE_KEY="your-key"

npm run dev

# Or with .env file
npm run dev

Ejecutando la versión compilada

npm run build
npm start

🛠️ Herramientas disponibles

Herramientas de migración de base de datos

list_migrations

Lista todas las migraciones de base de datos con su estado.

// No parameters required

deploy_migration

Implementa una nueva migración de base de datos.

{
  "sql": "CREATE TABLE users (id SERIAL PRIMARY KEY, email TEXT);",
  "name": "create_users_table"
}

execute_sql

Ejecuta consultas SQL sin procesar en la base de datos de Supabase.

{
  "sql": "SELECT * FROM users LIMIT 10;"
}

get_migration_status

Obtén el estado de una migración específica.

{
  "version": "20231201120000"
}

Herramientas de Edge Functions

list_edge_functions

Lista todas las edge functions implementadas.

deploy_edge_function

Implementa una nueva edge function.

{
  "name": "hello-world",
  "code": "export default function handler(req) { return new Response('Hello World'); }",
  "verify_jwt": true
}

delete_edge_function

Elimina una edge function.

{
  "name": "hello-world"
}

get_edge_function_logs

Obtén registros de una edge function.

{
  "name": "hello-world",
  "limit": 100
}

invoke_edge_function

Invoca una edge function.

{
  "name": "hello-world",
  "payload": { "key": "value" }
}

Herramientas de almacenamiento

list_storage_buckets

Lista todos los buckets de almacenamiento.

create_storage_bucket

Crea un nuevo bucket de almacenamiento.

{
  "id": "avatars",
  "public": true,
  "file_size_limit": 5242880
}

delete_storage_bucket

Elimina un bucket de almacenamiento.

{
  "id": "avatars"
}

Herramientas de autenticación y configuración

get_auth_config

Obtén la configuración de autenticación.

update_auth_config

Actualiza la configuración de autenticación.

{
  "config": {
    "site_url": "https://myapp.com",
    "enable_signup": true
  }
}

check_supabase_health

Verifica el estado de todos los servicios de Supabase.

get_supabase_version

Obtén información de la versión de Supabase.

verify_setup ⭐

Verifica la configuración del sistema y el estado de todos los servicios (Coolify, Supabase, CLI).

Esta herramienta integral verifica:

  • Conexión y autenticación de Coolify
  • Conexión y autenticación de Supabase
  • Accesibilidad de la base de datos
  • Disponibilidad de CLI
  • Tiempos de respuesta y estado del servicio

Devuelve: Informe de estado detallado con recomendaciones para cualquier problema encontrado.

Consulta docs/VERIFICATION.md para la guía completa de verificación.

Herramientas de gestión de Coolify

list_coolify_applications

Lista todas las aplicaciones de Coolify.

get_coolify_application

Obtén detalles de una aplicación específica.

{
  "uuid": "app-uuid-here"
}

update_coolify_application_env

Actualiza las variables de entorno de la aplicación.

{
  "uuid": "app-uuid-here",
  "env": {
    "NODE_ENV": "production",
    "API_KEY": "secret"
  }
}

deploy_coolify_application

Implementa una aplicación de Coolify.

{
  "uuid": "app-uuid-here"
}

start_coolify_application / stop_coolify_application / restart_coolify_application

Controla el ciclo de vida de la aplicación.

{
  "uuid": "app-uuid-here"
}

get_coolify_logs

Obtén registros de la aplicación.

{
  "uuid": "app-uuid-here",
  "lines": 100
}

Herramientas de implementación

deploy_supabase_to_coolify

Implementa una instancia completa de Supabase en Coolify.

{
  "name": "my-supabase",
  "config": {
    "postgres_version": "15",
    "enable_realtime": true,
    "enable_storage": true,
    "enable_auth": true,
    "custom_domain": "https://supabase.myapp.com",
    "environment_variables": {
      "CUSTOM_VAR": "value"
    }
  }
}

update_supabase_deployment

Actualiza una implementación existente de Supabase.

{
  "uuid": "app-uuid-here",
  "config": {
    "enable_graphql": true
  }
}

get_deployment_status

Obtén el estado de una implementación de Supabase.

{
  "uuid": "app-uuid-here"
}

📚 Recursos MCP

El servidor expone estos recursos para clientes MCP:

  • supabase://migrations - Todas las migraciones de base de datos
  • supabase://edge-functions - Todas las edge functions
  • supabase://storage-buckets - Todos los buckets de almacenamiento
  • supabase://auth-config - Configuración de autenticación
  • supabase://health - Estado de salud del servicio
  • coolify://applications - Todas las aplicaciones de Coolify
  • coolify://services - Todos los servicios de Coolify
  • coolify://databases - Todas las bases de datos de Coolify

🔒 Mejores prácticas de seguridad

  1. Nunca confirmes tokens de API en el control de versiones
  2. Usa variables de entorno para datos sensibles
  3. Restringe los permisos del token de API al mínimo requerido
  4. Rota los tokens regularmente
  5. Usa la clave de rol de servicio solo en servidores seguros
  6. Habilita la verificación JWT para edge functions
  7. Valida todas las entradas (automático con esquemas Zod)
  8. Verifica la configuración antes de implementaciones en producción
  9. Establece permisos de archivo adecuados en los archivos de configuración:
chmod 600 ~/.env
chmod 600 ~/Library/Application\ Support/Claude/claude_desktop_config.json

🧪 Pruebas y verificación

Compilación y verificación de tipos

# Run type checking
npm run typecheck

# Run linter
npm run lint

# Build project
npm run build

Verificar configuración

Después de iniciar el servidor, verifica que todo funcione:

# Start the server
npm start

# Then ask Claude:
"Run verify_setup to check if everything is configured correctly"

Consulta docs/VERIFICATION.md para la guía completa de verificación.

🔍 Diagnóstico y pruebas

Antes de reportar problemas o si tienes problemas de conexión, usa la herramienta de diagnóstico integrada:

Diagnóstico rápido

Ejecuta la herramienta de diagnóstico automatizada para verificar tu configuración:

# Using npm
npm run diagnose

# Or on Windows
.\diagnose.ps1

# Or on Linux/Mac
./diagnose.sh

La herramienta de diagnóstico verificará automáticamente:

  • ✅ Existencia y configuración del archivo .env
  • ✅ Variables de entorno requeridas
  • ✅ Conexión y autenticación de la API de Coolify
  • ✅ Conexión y autenticación de Supabase
  • ✅ Estado de todos los servicios de Supabase
  • ✅ Conectividad de red

Salida esperada (cuando funciona)

🟢 ALL CHECKS PASSED - MCP Server should work correctly

✅ Passed:   10
❌ Failed:   0
⚠️  Warnings: 0

Problemas de diagnóstico comunes

Archivo .env faltante

❌ .env file NOT found!

Solución: cp env.example .env y luego edita con tus credenciales

Valores de marcador de posición

❌ ENV: COOLIFY_API_TOKEN: Contains placeholder value

Solución: Reemplaza your-coolify-api-token-here con el token real del Panel de Coolify → Keys & Tokens

Clave de Supabase incorrecta

❌ Supabase Authentication: Invalid service role key

Solución: Asegúrate de usar la clave service_role, ¡NO la clave anon!
Obténla de: Panel de Supabase → Settings → API → clave service_role

Conexión fallida

❌ Coolify Connection: ECONNREFUSED

Solución: Verifica que Coolify esté ejecutándose y sea accesible en la URL configurada

Obtención de credenciales

Token de API de Coolify:

  1. Panel de Coolify → Perfil → Keys & Tokens → Tokens de API
  2. Haz clic en "Create New Token"
  3. Copia el token (¡no lo volverás a ver!)
  4. Añádelo a .env como COOLIFY_API_TOKEN

Clave de rol de servicio de Supabase:

  • Supabase Cloud: Panel → Settings → API → Copiar clave service_role
  • Autoalojado: Verifica las variables de entorno de la implementación de Coolify para SERVICE_ROLE_KEY

Guía de inicio rápido

Para solución de problemas detallada, consulta:

🐛 Solución de problemas

Problemas comunes

1. Variables de entorno faltantes

Error: Missing required environment variables: COOLIFY_API_URL, COOLIFY_API_TOKEN

Solución: Asegúrate de que todas las variables de entorno requeridas estén configuradas. Verifica tu archivo .env o la configuración de Claude Desktop.

2. Conexión fallida

Error: Failed to connect to Coolify API

Solución:

  • Verifica que la instancia de Coolify esté ejecutándose
  • Verifica que la URL de la API sea correcta (incluye http:// o https://)
  • Asegúrate de que el token de API tenga los permisos adecuados
  • Verifica la conectividad de red

3. Autenticación fallida

Error: Unauthorized o 401

Solución:

  • Verifica que los tokens de API sean correctos
  • Verifica que el token no haya expirado
  • Asegúrate de que el token tenga los permisos requeridos

4. El servidor MCP no aparece

Solución:

  • Reinicia Claude Desktop
  • Verifica que la ruta del archivo de configuración sea correcta para tu sistema operativo
  • Verifica la sintaxis JSON en la configuración
  • Revisa los registros del servidor para ver errores

Modo de depuración

Ejecuta con salida de depuración:

DEBUG=* npm start

📖 Ejemplos de casos de uso

1. Implementar una nueva instancia de Supabase

// Using the MCP tool
deploy_supabase_to_coolify({
  name: "production-supabase",
  config: {
    postgres_version: "15",
    enable_realtime: true,
    enable_storage: true,
    custom_domain: "https://api.myapp.com"
  }
})

2. Implementar migración de base de datos

deploy_migration({
  name: "add_user_profiles",
  sql: `
    CREATE TABLE user_profiles (
      id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
      user_id UUID REFERENCES auth.users(id),
      display_name TEXT,
      avatar_url TEXT,
      created_at TIMESTAMP DEFAULT NOW()
    );
  `
})

3. Implementar edge function

deploy_edge_function({
  name: "send-email",
  code: `
    import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'
    
    serve(async (req) => {
      const { to, subject, body } = await req.json()
      // Send email logic here
      return new Response(JSON.stringify({ success: true }))
    })
  `,
  verify_jwt: true
})

4. Monitorear el estado de la implementación

// Check overall health
check_supabase_health()

// Get specific deployment status
get_deployment_status({ uuid: "your-app-uuid" })

// View logs
get_coolify_logs({ uuid: "your-app-uuid", lines: 100 })

🤝 Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar un Pull Request.

📄 Licencia

MIT

🔗 Enlaces

📞 Soporte

Para problemas y preguntas:

Nota: Este servidor MCP está diseñado para instancias de Supabase autoalojadas en Coolify. Proporciona capacidades de gestión integrales mientras mantiene la seguridad mediante variables de entorno y un manejo adecuado de tokens.