Supabase Coolify MCP Server

Servidor MCP abrangente para gerenciar Supabase auto-hospedado no Coolify com suporte completo a deploy, migrações, edge functions e rollback.

GitHub
3
Experimente este MCPPatrocinado

Documentação

Servidor MCP Supabase Coolify

npm version npm downloads License: MIT TypeScript Node Version

⚡ Instalação com Um Clique

Instale diretamente na sua ferramenta de codificação com 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: Após a instalação, você precisará configurar as variáveis de ambiente necessárias. Consulte Configuração abaixo.

Um servidor MCP (Model Context Protocol) abrangente em TypeScript para gerenciar Supabase auto-hospedado no Coolify. Este servidor permite que agentes de IA implantem migrações, publiquem edge functions, configurem serviços e gerenciem implantações Supabase com facilidade.

📦 Pacote NPM • 📚 Documentação • 🚀 Início Rápido

🚀 Recursos

Gerenciamento do Supabase

  • Migrações de Banco de Dados: Implante, acompanhe, reverta e gerencie migrações de banco de dados
  • Rollback de Migrações: Reverta migrações com segurança usando suporte a SQL down
  • Integração com Supabase CLI: Integração completa com a CLI para desenvolvimento e implantação locais
  • Edge Functions: Implante, invoque, monitore e exclua edge functions
  • Gerenciamento de Armazenamento: Crie e gerencie buckets de armazenamento
  • Configuração de Autenticação: Configure provedores e configurações de autenticação
  • Configuração em Tempo Real: Gerencie as configurações do serviço de tempo real
  • Monitoramento de Saúde: Verifique o status de todos os serviços do Supabase
  • Geração de Tipos: Gere tipos TypeScript a partir do esquema do banco de dados

Recursos de Produção

  • Validação de Entrada: Validação baseada em Zod para todas as entradas das ferramentas
  • Verificações de Saúde: Verificações automáticas de inicialização e ferramenta de verificação
  • Tratamento de Erros: Mensagens de erro abrangentes com dicas de solução de problemas
  • Segurança de Tipos: Suporte completo a TypeScript em todo o projeto

Integração com Coolify

  • Gerenciamento de Aplicações: Liste, implante, inicie, pare e reinicie aplicações
  • Gerenciamento de Serviços: Controle os serviços do Coolify
  • Gerenciamento de Banco de Dados: Gerencie bancos de dados hospedados no Coolify
  • Variáveis de Ambiente: Atualize a configuração de aplicações com segurança
  • Logs: Acesse logs de aplicações para depuração

Automação de Implantação

  • Implantação com Um Clique: Implante instâncias Supabase completas no Coolify
  • Gerenciamento de Configuração: Atualize as configurações de implantação dinamicamente
  • Monitoramento de Status: Acompanhe a saúde e o status da implantação

📋 Pré-requisitos

  • Node.js >= 18.0.0
  • Uma instância Coolify (auto-hospedada ou na nuvem)
  • Token da API do Coolify com permissões apropriadas
  • Uma instância Supabase auto-hospedada (ou pronta para implantar uma)

🔧 Instalação

Método 1: NPM (Recomendado)

Instale globalmente via NPM:

npm install -g supabase-coolify-mcp-server

Ou use diretamente com npx (sem necessidade de instalação):

npx supabase-coolify-mcp-server

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

Método 2: A partir do Código Fonte

Clone e compile a partir do GitHub:

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

⚙️ Configuração

Variáveis de Ambiente

Crie um arquivo .env ou defina as seguintes variáveis de ambiente:

# 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

Obtendo Tokens de API

Token da API do Coolify

  1. Faça login na sua instância Coolify
  2. Navegue até "Keys & Tokens" > "API tokens"
  3. Clique em "Create New Token"
  4. Selecione as permissões (recomendado: * para acesso total)
  5. Copie o token gerado

Chave de Função de Serviço do Supabase

Para Supabase auto-hospedado:

  1. Faça login no seu painel do Supabase
  2. Vá para Settings > API
  3. Copie a chave service_role (mantenha-a segura!)

Ou a partir das variáveis de ambiente da sua implantação Supabase:

echo $SERVICE_ROLE_KEY

🎯 Uso

⚠️ IMPORTANTE: Variáveis de Ambiente Necessárias

O servidor MCP requer variáveis de ambiente para conectar-se ao Coolify e ao Supabase.

Configuração Recomendada (Funciona para Todos):

Adicione variáveis de ambiente diretamente à sua configuração 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"
      }
    }
  }
}

Substitua os valores de exemplo pelas suas credenciais reais!

📖 Opções de Configuração

O servidor suporta três métodos para fornecer variáveis de ambiente (em ordem de prioridade):

  1. Seção env da Configuração MCP ⭐ RECOMENDADO - Funciona para todos, autocontido
  2. Variáveis de ambiente do sistema - Para usuários avançados que desejam credenciais fora da configuração
  3. Arquivo .env com script wrapper - Apenas para desenvolvimento local (não escalável)

Para instruções detalhadas de configuração para cada método, consulte: MCP_CONFIGURATION.md

Erro Comum: ❌ Deixar valores de exemplo como https://your-supabase-instance.example.com
Solução: ✅ Substitua TODOS os valores de exemplo pelas suas URLs e credenciais reais!

Com o Claude Desktop

Adicione à sua configuração do Claude Desktop:

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

Usando NPX (Recomendado - Sempre a Versão Mais Recente)

{
  "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 Instalação Global

Primeiro, instale globalmente:

npm install -g supabase-coolify-mcp-server

Depois, configure:

{
  "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 Desenvolvimento

# 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

Executando a Versão Compilada

npm run build
npm start

🛠️ Ferramentas Disponíveis

Ferramentas de Migração de Banco de Dados

list_migrations

Liste todas as migrações de banco de dados com seu status.

// No parameters required

deploy_migration

Implante uma nova migração de banco de dados.

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

execute_sql

Execute consulta SQL bruta no banco de dados Supabase.

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

get_migration_status

Obtenha o status de uma migração específica.

{
  "version": "20231201120000"
}

Ferramentas de Edge Functions

list_edge_functions

Liste todas as edge functions implantadas.

deploy_edge_function

Implante uma nova edge function.

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

delete_edge_function

Exclua uma edge function.

{
  "name": "hello-world"
}

get_edge_function_logs

Obtenha logs de uma edge function.

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

invoke_edge_function

Invoque uma edge function.

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

Ferramentas de Armazenamento

list_storage_buckets

Liste todos os buckets de armazenamento.

create_storage_bucket

Crie um novo bucket de armazenamento.

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

delete_storage_bucket

Exclua um bucket de armazenamento.

{
  "id": "avatars"
}

Ferramentas de Autenticação e Configuração

get_auth_config

Obtenha a configuração de autenticação.

update_auth_config

Atualize a configuração de autenticação.

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

check_supabase_health

Verifique a saúde de todos os serviços do Supabase.

get_supabase_version

Obtenha informações da versão do Supabase.

verify_setup ⭐

Verifique a configuração do sistema e a saúde de todos os serviços (Coolify, Supabase, CLI).

Esta ferramenta abrangente verifica:

  • Conexão e autenticação com o Coolify
  • Conexão e autenticação com o Supabase
  • Acessibilidade do banco de dados
  • Disponibilidade da CLI
  • Tempos de resposta e status dos serviços

Retorna: Relatório de saúde detalhado com recomendações para quaisquer problemas encontrados.

Consulte docs/VERIFICATION.md para o guia completo de verificação.

Ferramentas de Gerenciamento do Coolify

list_coolify_applications

Liste todas as aplicações do Coolify.

get_coolify_application

Obtenha detalhes de uma aplicação específica.

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

update_coolify_application_env

Atualize as variáveis de ambiente da aplicação.

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

deploy_coolify_application

Implante uma aplicação do Coolify.

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

start_coolify_application / stop_coolify_application / restart_coolify_application

Controle o ciclo de vida da aplicação.

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

get_coolify_logs

Obtenha logs da aplicação.

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

Ferramentas de Implantação

deploy_supabase_to_coolify

Implante uma instância Supabase completa no 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

Atualize uma implantação Supabase existente.

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

get_deployment_status

Obtenha o status de uma implantação Supabase.

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

📚 Recursos MCP

O servidor expõe estes recursos para clientes MCP:

  • supabase://migrations - Todas as migrações de banco de dados
  • supabase://edge-functions - Todas as edge functions
  • supabase://storage-buckets - Todos os buckets de armazenamento
  • supabase://auth-config - Configuração de autenticação
  • supabase://health - Status de saúde dos serviços
  • coolify://applications - Todas as aplicações do Coolify
  • coolify://services - Todos os serviços do Coolify
  • coolify://databases - Todos os bancos de dados do Coolify

🔒 Boas Práticas de Segurança

  1. Nunca envie tokens de API para o controle de versão
  2. Use variáveis de ambiente para dados sensíveis
  3. Restrinja as permissões do token de API ao mínimo necessário
  4. Rotacione os tokens regularmente
  5. Use a chave de função de serviço apenas em servidores seguros
  6. Ative a verificação JWT para edge functions
  7. Valide todas as entradas (automático com esquemas Zod)
  8. Verifique a configuração antes de implantações em produção
  9. Defina permissões de arquivo apropriadas nos arquivos de configuração:
chmod 600 ~/.env
chmod 600 ~/Library/Application\ Support/Claude/claude_desktop_config.json

🧪 Testes e Verificação

Compilação e Verificação de Tipos

# Run type checking
npm run typecheck

# Run linter
npm run lint

# Build project
npm run build

Verificar Configuração

Após iniciar o servidor, verifique se tudo está funcionando:

# Start the server
npm start

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

Consulte docs/VERIFICATION.md para o guia completo de verificação.

🔍 Diagnóstico e Testes

Antes de relatar problemas ou se estiver tendo problemas de conexão, use a ferramenta de diagnóstico integrada:

Diagnóstico Rápido

Execute a ferramenta de diagnóstico automatizada para verificar sua configuração:

# Using npm
npm run diagnose

# Or on Windows
.\diagnose.ps1

# Or on Linux/Mac
./diagnose.sh

A ferramenta de diagnóstico verificará automaticamente:

  • ✅ Existência e configuração do arquivo .env
  • ✅ Variáveis de ambiente necessárias
  • ✅ Conexão e autenticação com a API do Coolify
  • ✅ Conexão e autenticação com o Supabase
  • ✅ Saúde de todos os serviços do Supabase
  • ✅ Conectividade de rede

Saída Esperada (Quando Funcionando)

🟢 ALL CHECKS PASSED - MCP Server should work correctly

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

Problemas Comuns de Diagnóstico

Arquivo .env Ausente

❌ .env file NOT found!

Correção: cp env.example .env e depois edite com suas credenciais

Valores de Exemplo

❌ ENV: COOLIFY_API_TOKEN: Contains placeholder value

Correção: Substitua your-coolify-api-token-here pelo token real do Painel do Coolify → Keys & Tokens

Chave Supabase Incorreta

❌ Supabase Authentication: Invalid service role key

Correção: Certifique-se de estar usando a chave service_role, NÃO a chave anon!
Obtenha-a em: Painel do Supabase → Settings → API → chave service_role

Falha na Conexão

❌ Coolify Connection: ECONNREFUSED

Correção: Verifique se o Coolify está em execução e acessível na URL configurada

Obtendo Credenciais

Token da API do Coolify:

  1. Painel do Coolify → Profile → Keys & Tokens → API Tokens
  2. Clique em "Create New Token"
  3. Copie o token (você não o verá novamente!)
  4. Adicione ao .env como COOLIFY_API_TOKEN

Chave de Função de Serviço do Supabase:

  • Supabase Cloud: Painel → Settings → API → Copiar chave service_role
  • Auto-hospedado: Verifique as variáveis de ambiente da implantação no Coolify para SERVICE_ROLE_KEY

Guia de Início Rápido

Para solução de problemas detalhada, consulte:

🐛 Solução de Problemas

Problemas Comuns

1. Variáveis de Ambiente Ausentes

Erro: Missing required environment variables: COOLIFY_API_URL, COOLIFY_API_TOKEN

Solução: Certifique-se de que todas as variáveis de ambiente necessárias estejam definidas. Verifique seu arquivo .env ou a configuração do Claude Desktop.

2. Falha na Conexão

Erro: Failed to connect to Coolify API

Solução:

  • Verifique se a instância Coolify está em execução
  • Verifique se a URL da API está correta (inclua http:// ou https://)
  • Certifique-se de que o token da API tenha as permissões adequadas
  • Verifique a conectividade de rede

3. Falha na Autenticação

Erro: Unauthorized ou 401

Solução:

  • Verifique se os tokens de API estão corretos
  • Verifique se o token não expirou
  • Certifique-se de que o token tenha as permissões necessárias

4. Servidor MCP Não Aparece

Solução:

  • Reinicie o Claude Desktop
  • Verifique se o caminho do arquivo de configuração está correto para seu sistema operacional
  • Verifique a sintaxe JSON na configuração
  • Verifique os logs do servidor para erros

Modo de Depuração

Execute com saída de depuração:

DEBUG=* npm start

📖 Exemplos de Casos de Uso

1. Implantar uma Nova Instância 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. Implantar Migração de Banco de Dados

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. Implantar 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. Monitorar Saúde da Implantação

// 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 })

🤝 Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

📄 Licença

MIT

🔗 Links

📞 Suporte

Para problemas e dúvidas:

Nota: Este servidor MCP foi projetado para instâncias Supabase auto-hospedadas no Coolify. Ele oferece capacidades abrangentes de gerenciamento, mantendo a segurança por meio de variáveis de ambiente e tratamento adequado de tokens.