Supabase MCP Server

Um servidor MCP que fornece controle administrativo sobre um banco de dados PostgreSQL do Supabase, compatível com o Cursor's Composer e o Codeium's Cascade.

GitHub
12
Experimente este MCPPatrocinado

Documentação

Supabase MCP Server 🚀

TypeScript Supabase PostgreSQL Node.js MCP Windsurf

🔥 Um poderoso servidor Model Context Protocol (MCP) que fornece controle administrativo completo sobre seu banco de dados Supabase PostgreSQL através do Composer do Cursor e do Cascade da Codeium. Esta ferramenta permite gerenciamento de banco de dados sem interrupções com recursos abrangentes para operações de tabelas, gerenciamento de registros, modificações de esquema e muito mais.

Supabase

📚 Sumário

🔧 Pré-requisitos

  • Node.js >= 16.x
  • npm >= 8.x
  • Um projeto Supabase com:
    • ID do projeto
    • Senha do banco de dados
    • String de conexão PostgreSQL
  • IDE Cursor ou Cascade da Codeium (para usuários pagantes)

🚀 Início Rápido

📥 Instalação

# Clone the repository
git clone https://github.com/Quegenx/supabase-mcp-server.git
cd supabase-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

⚙️ Configuração

  1. Instale as dependências e compile o projeto:

    npm install
npm run build

  2. Nas configurações de MCP do Cursor, adicione o servidor com este comando:

    /opt/homebrew/bin/node /path/to/dist/index.js postgresql://postgres.[PROJECT-ID]:[PASSWORD]@aws-0-eu-central-1.pooler.supabase.com:5432/postgres

    Substitua:

    • /path/to/dist/index.js pelo seu caminho real
    • [PROJECT-ID] pelo ID do seu projeto Supabase
    • [PASSWORD] pela senha do seu banco de dados

Nota: Mantenha suas credenciais de banco de dados seguras e nunca as envie para o controle de versão.

🎯 Integrações

Integração MCP com Cursor

O Model Context Protocol (MCP) permite fornecer ferramentas personalizadas para LLMs agentivos no Cursor. Este servidor pode ser integrado ao recurso Composer do Cursor, fornecendo acesso direto a todas as ferramentas de gerenciamento de banco de dados por meio de comandos em linguagem natural.

Configuração no Cursor

  1. Abra Configurações do Cursor > Recursos > MCP

  2. Clique no botão "+ Adicionar Novo Servidor MCP"

  3. Preencha o formulário modal:

    • Nome: "Supabase MCP" (ou qualquer apelido que preferir)
    • Tipo: command (transporte stdio)
    • Comando: Sua string de comando completa com os detalhes de conexão

  4. Compile o projeto primeiro:

    npm install
npm run build

  5. Obtenha o caminho do seu Node.js:

    # On Mac/Linux
which node
# On Windows
where node

  6. Adicione o comando do servidor:

    /path/to/node /path/to/dist/index.js postgresql://postgres.[PROJECT-ID]:[PASSWORD]@aws-0-eu-central-1.pooler.supabase.com:5432/postgres

    Substitua:

    • /path/to/node pelo caminho real do seu Node.js (do passo 5)
    • /path/to/dist/index.js pelo caminho real do arquivo JavaScript compilado
    • [PROJECT-ID] pelo ID do seu projeto Supabase
    • [PASSWORD] pela senha do seu banco de dados

  7. Clique em "Adicionar Servidor" e depois clique no botão de atualizar no canto superior direito

Usando as Ferramentas no Cursor

O Agente Composer detectará e usará automaticamente as ferramentas relevantes quando você descrever suas tarefas de banco de dados. Por exemplo:

  • "Liste todas as tabelas do meu banco de dados"
  • "Crie uma nova tabela de usuários"
  • "Adicione um índice à coluna de e-mail"

Quando o agente usar uma ferramenta, você verá:

  1. Um prompt para aprovar/negar a chamada da ferramenta
  2. Os argumentos da chamada da ferramenta (expansíveis)
  3. A resposta após a aprovação

Nota: Para servidores stdio como este, o comando deve ser um comando shell válido. Se você precisar de variáveis de ambiente, considere usar um script wrapper.

Integração Windsurf/Cascade

Este servidor MCP também suporta a integração com o Cascade (Windsurf) da Codeium. Observe que este recurso está atualmente disponível apenas para usuários individuais pagantes (não disponível para usuários de Teams ou Enterprise).

Configuração com Cascade

  1. Crie ou edite ~/.codeium/windsurf/mcp_config.json:

    {
  "mcpServers": {
    "supabase-mcp": {
      "command": "/path/to/node",
      "args": [
        "/path/to/dist/index.js",
        "postgresql://postgres.[PROJECT-ID]:[PASSWORD]@aws-0-eu-central-1.pooler.supabase.com:5432/postgres"
      ]
    }
  }
}

  2. Acesso rápido à configuração:

    • Encontre a barra de ferramentas acima da entrada do Cascade
    • Clique no ícone de martelo
    • Clique em "Configurar" para abrir o mcp_config.json

  3. Substitua na configuração:

    • /path/to/node pelo caminho real do seu Node.js
    • /path/to/dist/index.js pelo seu caminho real
    • [PROJECT-ID] pelo ID do seu projeto Supabase
    • [PASSWORD] pela senha do seu banco de dados

  4. No Cascade:

    • Clique no ícone de martelo na barra de ferramentas
    • Clique em "Configurar" para verificar sua configuração
    • Clique em "Atualizar" para carregar o servidor MCP
    • Clique no nome do servidor para ver as ferramentas disponíveis

Notas Importantes para Usuários do Cascade

  • Apenas a funcionalidade de ferramentas é suportada (sem prompts ou recursos)
  • Chamadas de ferramentas MCP consumirão créditos independentemente de sucesso ou falha
  • Saída de imagem não é suportada
  • Apenas o tipo de transporte stdio é suportado
  • Chamadas de ferramentas podem invocar código escrito por implementadores de servidor arbitrários
  • O Cascade não assume responsabilidade por falhas em chamadas de ferramentas MCP

✨ Recursos

🎯 Ferramentas de Banco de Dados Disponíveis

Gerenciamento de Tabelas

  • Tabelas: list_tables, create_table, drop_table, rename_table
  • Colunas: add_column, drop_column, alter_column
  • Registros: fetch_records, create_record, update_record, delete_record

Índices e Restrições

  • Índices: list_indexes, create_index, delete_index, update_index
  • Restrições: list_constraints, add_constraint, remove_constraint, update_constraint

Funções e Triggers do Banco de Dados

  • Funções: list_functions, create_function, update_function, delete_function
  • Triggers: list_triggers, create_trigger, update_trigger, delete_trigger

Segurança e Controle de Acesso

  • Políticas: list_policies, create_policy, update_policy, delete_policy
  • Papéis: list_roles, create_role, update_role, delete_role

Gerenciamento de Armazenamento

  • Buckets: list_buckets, create_bucket, delete_bucket
  • Arquivos: delete_file, bulk_delete_files
  • Pastas: list_folders

Tipos de Dados e Publicações

  • Tipos Enumerados: list_enumerated_types, create_enumerated_type, update_enumerated_type, delete_enumerated_type
  • Publicações: list_publications, create_publication, update_publication, delete_publication

Recursos em Tempo Real

  • Políticas: list_realtime_policies, create_realtime_policy, update_realtime_policy, delete_realtime_policy
  • Canais: list_realtime_channels, manage_realtime_channels, send_realtime_message, get_realtime_messages
  • Gerenciamento: manage_realtime_status, manage_realtime_views

Gerenciamento de Usuários

  • Autenticação: list_users, create_user, update_user, delete_user

Acesso Direto a SQL

  • Consulta: query - Execute consultas SQL personalizadas

🚀 Principais Benefícios

  • Controle por Linguagem Natural: Gerencie seu banco de dados Supabase por meio de comandos conversacionais simples
  • Cobertura Abrangente: Conjunto completo de ferramentas cobrindo tabelas, registros, índices, funções, segurança e muito mais
  • Integração Perfeita: Funciona diretamente no Composer do Cursor e no Cascade da Codeium
  • Amigável para Desenvolvedores: Reduz a alternância de contexto entre a IDE e as ferramentas de gerenciamento de banco de dados
  • Acesso Seguro: Mantém a segurança do seu banco de dados com autenticação adequada

📁 Estrutura do Projeto

supabase-mcp-server/
├── dist/                    # Compiled JavaScript files
│   ├── index.d.ts          # TypeScript declarations
│   └── index.js            # Main JavaScript file
├── src/                    # Source code
│   └── index.ts           # Main TypeScript file
├── package.json           # Project configuration
├── package-lock.json      # Dependency lock file
└── tsconfig.json         # TypeScript configuration

💡 Uso

Uma vez configurado, o servidor MCP fornece todas as ferramentas de gerenciamento de banco de dados através do Composer do Cursor. Basta descrever o que você deseja fazer com seu banco de dados, e a IA usará os comandos apropriados.

Exemplos:

  • 📋 "Mostre-me todas as tabelas do meu banco de dados"
  • ➕ "Crie uma nova tabela de usuários com colunas id, nome e e-mail"
  • 🔍 "Adicione um índice na coluna de e-mail da tabela de usuários"

🔒 Notas de Segurança

  • 🔐 Mantenha sua string de conexão do banco de dados segura
  • ⚠️ Nunca envie credenciais sensíveis para o controle de versão
  • 👮 Use controles de acesso e permissões apropriados
  • 🛡️ Valide e sanitize todas as entradas para prevenir injeção de SQL

🛠️ Solução de Problemas

Problemas Comuns de Conexão

  1. Problemas com o Caminho do Node.js

    • Certifique-se de estar usando o caminho correto do Node.js
    • No Mac/Linux: Use which node para encontrar o caminho correto
    • No Windows: Use where node para encontrar o caminho correto
    • Substitua /usr/local/bin/node pelo caminho real do seu Node.js

  2. Problemas com Caminhos de Arquivo

    • Use caminhos absolutos em vez de caminhos relativos
    • No Mac/Linux: Use pwd no diretório do projeto para obter o caminho completo
    • No Windows: Use cd para obter o caminho completo
    • Exemplo: /Users/username/projects/supabase-mcp-server/dist/index.js

  3. MCP Não Detectando Ferramentas

    • Clique no botão de atualizar nas configurações de MCP do Cursor
    • Certifique-se de que o servidor está em execução (sem mensagens de erro)
    • Verifique se sua string de conexão está correta
    • Verifique se suas credenciais do Supabase são válidas

  4. Problemas de Permissão

    • Certifique-se de que o diretório dist existe (execute npm run build)
    • Verifique as permissões de arquivo (chmod +x em sistemas Unix)
    • Execute npm install com permissões apropriadas

Modo de Depuração

Adicione DEBUG=true antes do seu comando para ver logs detalhados:

DEBUG=true /usr/local/bin/node /path/to/dist/index.js [connection-string]

Notas Específicas por Plataforma

Usuários Windows

# Use this format for the command
"C:\\Program Files\\nodejs\\node.exe" "C:\\path\\to\\dist\\index.js" "postgresql://..."

Usuários Linux

# Find Node.js path
which node

# Make script executable
chmod +x /path/to/dist/index.js

Se você ainda estiver enfrentando problemas, por favor abra uma issue com:

  • Seu sistema operacional
  • Versão do Node.js (node --version)
  • Mensagem de erro completa
  • Passos para reproduzir

🤝 Contribuição

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

📄 Licença

Feito com ❤️ para a comunidade Cursor

Cursor • Supabase • GitHub