Supabase MCP — Casos de uso, Instalar & Demo ao vivo

Por que usar

Principais recursos

Ramificação de banco de dados para testes seguros de migração (plano Pro)
Execute SQL diretamente (leitura e escrita)
Gere e aplique migrações de banco de dados
Implante Edge Functions (Deno) pelo chat
Inspecione logs (postgres, edge-function, auth, realtime)
Flag de modo somente leitura para uso mais seguro em prod

Demo ao vivo

Como fica na prática

supabase.replay ▶ pronto

0/0

Instalar

Escolha seu cliente

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

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": [
        "-y",
        "@supabase/mcp-server-supabase"
      ]
    }
  }
}

Abra Claude Desktop → Settings → Developer → Edit Config. Reinicie após salvar.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": [
        "-y",
        "@supabase/mcp-server-supabase"
      ]
    }
  }
}

Cursor usa o mesmo esquema mcpServers que o Claude Desktop. Config de projeto vence a global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": [
        "-y",
        "@supabase/mcp-server-supabase"
      ]
    }
  }
}

Clique no ícone MCP Servers na barra lateral do Cline, depois "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": [
        "-y",
        "@supabase/mcp-server-supabase"
      ]
    }
  }
}

Mesmo formato do Claude Desktop. Reinicie o Windsurf para aplicar.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "supabase",
      "command": "npx",
      "args": [
        "-y",
        "@supabase/mcp-server-supabase"
      ]
    }
  ]
}

O Continue usa um array de objetos de servidor em vez de um map.

~/.config/zed/settings.json

{
  "context_servers": {
    "supabase": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "@supabase/mcp-server-supabase"
        ]
      }
    }
  }
}

Adicione em context_servers. Zed recarrega automaticamente ao salvar.

claude mcp add supabase -- npx -y @supabase/mcp-server-supabase

Uma linha só. Verifique com claude mcp list. Remova com claude mcp remove.

Casos de uso

Usos do mundo real: Supabase

Teste uma migração destrutiva em uma branch de banco de dados antes de aplicar em prod

👤 Engenheiros implementando mudanças de schema ⏱ ~30 min advanced

Quando usar: Você tem uma migração que descarta uma coluna ou preenche milhões de linhas, e quer fazer uma dry-run em uma branch com dados reais primeiro.

Pré-requisitos

Plano Supabase Pro ou superior — Ramificação é restrita a planos pagos
Token de acesso pessoal — supabase.com/dashboard/account/tokens — escopo para sua org

Fluxo

Crie uma branch a partir de prod

Crie uma branch de banco de dados nomeada 'test-drop-legacy-col' baseada na branch principal no projeto <ref>. Aguarde até que esteja pronta.✓ Copiado

→ Branch criada com sua própria string de conexão
Execute a migração na branch

Aplique a seguinte migração na nova branch: <paste SQL>. Relatar linhas afetadas e erros.✓ Copiado

→ Migração executada; contagens de linhas visíveis
Verifique e promova ou descarte

Execute SELECTs de sanidade na branch (10 primeiras linhas de tabelas afetadas, contagens de NULL em colunas alteradas). Se parecer correto, me avise e eu promovo; caso contrário, delete a branch.✓ Copiado

→ Saída de verificação, depois go/no-go explícito do usuário

Resultado: Migração validada contra a forma real dos dados antes de tocar em prod.

Armadilhas

Branches não têm os dados exatos de prod — são um snapshot no momento de criação da branch — Anote o timestamp do snapshot; se sua migração é sensível a linhas recentes, crie a branch o mais próximo possível do momento de aplicação
Criação de branch consome horas de computação — Sempre delete a branch após testes; branches abandonadas acumulam cobrança

Combine com: github · postgres

Escreva e implante uma Supabase Edge Function pelo chat

👤 Devs adicionando pequenos endpoints de backend (webhooks, geradores de URL assinada, etc.) ⏱ ~20 min intermediate

Quando usar: Você precisa de um endpoint HTTP rápido com acesso a BD — perfeito para uma Edge Function — e não quer trocar de contexto para o dashboard.

Fluxo

Estruture a função

Crie uma Edge Function stripe-webhook no projeto <ref>. Deve: validar a assinatura Stripe, depois INSERT uma linha na tabela stripe_events. Use importações estilo Deno.✓ Copiado

→ Código da função escrito com convenções Deno adequadas
Implante

Implante stripe-webhook no projeto <ref>. Mostre-me a URL resultante.✓ Copiado

→ URL implantada retornada
Teste com um payload de amostra

Faça POST de um payload de teste para a URL e acompanhe os logs da função. Funcionou e escreveu uma linha?✓ Copiado

→ Logs mostram invocação; linha visível na tabela

Resultado: Um endpoint ativo mais uma linha no BD para provar que funciona, em 5 minutos.

Armadilhas

Secrets (STRIPE_SECRET) não são injetados automaticamente — Configure-os via dashboard Supabase ou ferramenta MCP set_secrets antes de invocar; referencie via Deno.env.get('STRIPE_SECRET')
Edge functions cold-start; primeira requisição é lenta — Invoque uma vez após implantação para aquecer antes de declarar 'funciona'

Combine com: stripe · github

Audite políticas de Row-Level Security em um projeto Supabase

👤 Devs e revisores conscientes de segurança ⏱ ~25 min intermediate

Quando usar: Antes do lançamento — você quer confirmar que RLS está ativado para cada tabela e as políticas realmente fazem o que você pensa.

Fluxo

Liste tabelas e estado de RLS

Liste todas as tabelas no schema public. Para cada uma, RLS está habilitado? Liste as políticas anexadas.✓ Copiado

→ Status de RLS por tabela mais corpos de políticas
Encontre tabelas sem RLS

Destaque qualquer tabela onde RLS está OFF, ou RLS está ON mas nenhuma política existe (efetivamente deny-all silenciosamente).✓ Copiado

→ Lista de risco com categoria clara para cada uma
Teste como anônimo

Para 3 tabelas sensíveis, simule uma consulta de usuário anônimo (usando a função anon). Retorna linhas? Não deveria.✓ Copiado

→ Resultados vazios = bom; linhas retornadas = bug de política

Resultado: Uma aprovação pré-lançamento na postura de autenticação, com evidência por tabela.

Armadilhas

RLS desativado em uma tabela que você pensava ser interna — A chave service_role ignora RLS por design — nunca a exponha no lado do cliente. Audite quais chaves são usadas onde

Investigue por que um usuário não consegue fazer login

👤 Engenheiros de suporte, fundadores fazendo atendimento de primeira linha ⏱ ~10 min beginner

Quando usar: Um usuário relata 'meu link de login não funciona' e você quer ver se o email foi enviado, quais eventos de autenticação foram disparados, etc.

Fluxo

Encontre o usuário

Encontre o usuário de autenticação com email '[email protected]'. Mostre created_at, last_sign_in_at, email_confirmed_at.✓ Copiado

→ Registro de usuário ou veredicto 'não encontrado'
Verifique logs de autenticação recentes

Puxe entradas de log de autenticação para esse user_id nas últimas 24h. Agrupe por tipo de evento.✓ Copiado

→ Sequência de eventos de autenticação (otp_sent, sign_in_failed, etc.)
Resolva

Com base nos eventos, qual é o problema real? Sugira a correção (reenviar convite, confirmar manualmente, redefinir senha).✓ Copiado

→ Diagnóstico mais plano de ação

Resultado: Um ticket de suporte resolvido com trilha de auditoria, em 5 minutos.

Armadilhas

PII flui para logs de chat — Evite colar registros de usuário brutos no histórico de chat que é arquivado; oculte emails ao resumir

Gere tipos TypeScript a partir do seu schema Supabase

👤 Devs frontend usando `supabase-js` ⏱ ~10 min beginner

Quando usar: Você alterou seu schema de BD e quer que os tipos de cliente sejam atualizados para corresponder.

Fluxo

Gere tipos

Gere tipos TypeScript para o schema public do projeto <ref>. Salve em src/types/database.ts.✓ Copiado

→ Arquivo de tipos escrito
Diff e verifique o uso

Comparado ao arquivo de tipos anterior (em git), o que mudou? Alguma das mudanças é quebra para sites de chamada existentes em src/?✓ Copiado

→ Análise de impacto por mudança
Abra PR

Commit a atualização de tipos mais qualquer correção de site de chamada necessária. Abra um PR intitulado 'chore: regen db types YYYY-MM-DD'.✓ Copiado

→ PR aberto com diff completo

Resultado: Tipos permanecem sincronizados com schema; sites de chamada quebrados detectados na hora do PR, não em produção.

Armadilhas

Tipos gerados não incluem visualizações a menos que a visualização tenha SECURITY INVOKER definido — Adicione visualizações explicitamente ou documente a lacuna; supabase-js as manipula com from('view_name') independentemente

Combine com: github · filesystem

Combinações

Combine com outros MCPs para 10× de alavancagem

supabase + github

Abra um PR com uma migração, implante em uma branch, anexe resultados de teste ao PR

Abra um PR adicionando a migração em supabase/migrations/. Crie uma branch Supabase com a migração aplicada. Comente no PR com os resultados de teste da branch.✓ Copiado

supabase + stripe

Crie uma Stripe webhook Edge Function que escreve eventos em Supabase

Crie uma Edge Function que recebe webhooks Stripe, valida a assinatura e insere eventos em uma tabela stripe_events. Configure o endpoint do webhook em Stripe para apontá-lo.✓ Copiado

supabase + filesystem

Sincronize arquivos de migração SQL locais com estado do projeto Supabase

Compare /supabase/migrations/ no disco para migrações aplicadas no projeto. Aplique qualquer uma ausente em ordem.✓ Copiado

Ferramentas

O que este MCP expõe

Ferramenta	Entradas	Quando chamar	Custo
list_projects	none	Descubra quais projetos seu token pode acessar	free
get_project / pause_project / restore_project	project_id: str	Inspecione ou controle um projeto	free
create_branch / list_branches / merge_branch / delete_branch	project_id, name?	Ramificação de banco de dados para testes de migração (Pro+)	Branch compute hours billed
list_tables	project_id, schemas?: str[]	Introspecção de schema	free
list_extensions / list_migrations	project_id	Metadados de BD	free
apply_migration	project_id, name: str, query: str	Aplique uma migração rastreada ao BD do projeto	free
execute_sql	project_id, query: str	SQL ad-hoc — leitura ou escrita	free
list_edge_functions / get_edge_function / deploy_edge_function	project_id, function name, code, entrypoint	Gerencie edge functions baseadas em Deno	Edge function invocations billed
get_logs	project_id, service: 'postgres'\|'auth'\|'edge-function'\|...	Puxe logs recentes de um serviço	free
generate_typescript_types	project_id	Regenere tipos de cliente após mudanças de schema	free
get_anon_key / get_project_url / get_advisors	project_id	Metadados de projeto; advisors sinalizam problemas de segurança ou desempenho	free

Custo e limites

O que custa rodar

Cota de API: Limites de taxa padrão do Supabase por plano
Tokens por chamada: Consultas de schema: pequenas. Logs e resultados SQL: depende do volume de dados — sempre defina limites de tempo/linha
Monetário: MCP gratuito; projeto Supabase é por plano ($0 free tier; Pro $25/mo). Ramificação consome horas de computação.
Dica: Branches são ótimas para testes mas caras quando esquecidas. Sempre delete_branch após mesclar ou quando descartadas.

Segurança

Permissões, segredos, alcance

Escopos mínimos: token de acesso pessoal com escopo para projetos específicos quando possível

Armazenamento de credenciais: Token de acesso pessoal em var env SUPABASE_ACCESS_TOKEN

Saída de dados: Todas as chamadas para api.supabase.com e endpoint regional do seu projeto

Nunca conceda: chave service_role para o agente a menos que absolutamente necessário — ela ignora RLS

Tokens de acesso pessoal têm alcance em toda a org por padrão — escopo para projetos específicos no dashboard.
execute_sql pode fazer qualquer coisa — UPDATE, DROP, GRANT. Use modo somente leitura (flag env) para trabalho em prod.
Código Edge Function é executado em seu projeto; evite implantar código do chat sem revisar o diff.

Solução de problemas

Erros comuns e correções

Não autorizado — token inválido

Token expirado ou escopo errado. Gere um novo em supabase.com/dashboard/account/tokens.

Verificar: curl -H 'Authorization: Bearer $TOKEN' https://api.supabase.com/v1/projects

Ferramentas de ramificação falham com 'plano não suporta ramificação'

Ramificação é Pro+. Atualize o plano ou pule fluxos de ramificação.

Implantação de Edge Function falha: 'código Deno inválido'

Código da função deve ser compatível com Deno (sem require estilo Node). Verifique se importações usam https://deno.land/... ou especificadores npm:.

execute_sql retorna 'permissão negada'

O MCP usa uma função com escopo de projeto. Para operações privilegiadas, execute via editor SQL do dashboard. Não conceda à função MCP superusuário.

Alternativas

Supabase vs. outros

Alternativa	Quando usar	Troca
Postgres MCP	Você precisa apenas de acesso SQL somente leitura e não precisa de recursos específicos do Supabase	Sem ramificação, edge functions, introspecção de autenticação ou logs
Neon MCP	Você está em Neon — também tem ramificação	Plataforma diferente; sem autenticação/edge functions
Supabase CLI directly	Você quer fluxo completo de desenvolvimento local com `supabase start`	Sem ergonomia de agente; melhor para fluxos comprometidos

Mais

Recursos

📖 Leia o README oficial no GitHub

🐙 Ver issues abertas

🔍 Ver todos os 400+ servidores MCP e Skills