Supabase MCP

Supabase MCP Server

Conecte seus projetos Supabase ao Cursor, Claude, Windsurf e outros assistentes de IA.

O Model Context Protocol (MCP) padroniza como Modelos de Linguagem de Grande Escala (LLMs) se comunicam com serviços externos como o Supabase. Ele conecta assistentes de IA diretamente ao seu projeto Supabase e permite que realizem tarefas como gerenciar tabelas, buscar configurações e consultar dados. Veja a lista completa de ferramentas.

Configuração

1. Siga nossas práticas recomendadas de segurança

Antes de configurar o servidor MCP, recomendamos que você leia nossas práticas recomendadas de segurança para entender os riscos de conectar um LLM aos seus projetos Supabase e como mitigá-los.

2. Configure seu cliente MCP

Para configurar o servidor Supabase MCP no seu cliente, visite nossa documentação de configuração. Você também pode gerar uma URL MCP personalizada para o seu projeto acessando a aba de conexão MCP no painel do Supabase.

Seu cliente MCP solicitará automaticamente que você faça login no Supabase durante a configuração. Certifique-se de escolher a organização que contém o projeto com o qual deseja trabalhar.

A maioria dos clientes MCP requer as seguintes informações:

{
  "mcpServers": {
    "supabase": {
      "type": "http",
      "url": "https://mcp.supabase.com/mcp"
    }
  }
}

Se você não encontrar seu cliente MCP listado em nossa documentação, verifique a documentação MCP do seu cliente e copie as informações MCP acima no formato esperado por ele (json, yaml, etc).

CLI

Se você estiver executando o Supabase localmente com a Supabase CLI, poderá acessar o servidor MCP em http://localhost:54321/mcp. Atualmente, o Servidor MCP em ambientes CLI oferece um subconjunto limitado de ferramentas e sem OAuth 2.1.

Self-hosted

Para Supabase self-hosted, consulte a página Habilitando servidor MCP. Atualmente, o Servidor MCP em ambientes self-hosted oferece um subconjunto limitado de ferramentas e sem OAuth 2.1.

Opções de configuração e ferramentas

Consulte a documentação do Supabase MCP Server para a lista completa de ferramentas disponíveis e opções de configuração.

A documentação também apresenta um construtor de URL interativo para preencher as opções de configuração para você.

Riscos de segurança

[!TIP] Antes de usar o servidor MCP, revise os riscos de segurança e as mitigações recomendadas na Documentação do Supabase.

Uso com o Cliente MCP do AI SDK

O pacote @supabase/mcp-server-supabase exporta createToolSchemas() para preencher esquemas de entrada e saída para o cliente MCP do Vercel AI SDK. Isso permite que as ferramentas do Supabase MCP sejam tratadas como ferramentas estáticas com validação do lado do cliente e tipos TypeScript inferidos para suas entradas e saídas.

import { createToolSchemas } from '@supabase/mcp-server-supabase';
import { createMCPClient } from '@ai-sdk/mcp';
import { streamText } from 'ai';

const mcpClient = await createMCPClient({
  transport: {
    type: 'http',
    url: 'https://mcp.supabase.com/mcp',
  },
});

const tools = await mcpClient.tools({
  schemas: createToolSchemas(),
});

const result = streamText({ model, tools, prompt: '...' });

for (const step of await result.steps) {
  for (const toolResult of step.staticToolResults) {
    if (toolResult.toolName === 'get_project_url') {
      toolResult.input;  // { project_id: string }
      toolResult.output; // { url: string }
    }
  }
}

createToolSchemas() aceita opções de filtragem semelhantes aos parâmetros de URL do servidor MCP:

• features: Restringe a grupos de recursos específicos (ex.: ['database', 'docs']). O padrão são todos os grupos de recursos padrão.
• projectScoped: Quando true, omite project_id dos esquemas de entrada da ferramenta e exclui ferramentas em nível de conta — use ao conectar a um servidor configurado com project_ref. O padrão é false.
• readOnly: Quando true, exclui ferramentas de mutação — use ao conectar a um servidor configurado com read_only=true. O padrão é false.

const mcpClient = await createMCPClient({
  transport: {
    type: 'http',
    url: 'https://mcp.supabase.com/mcp?project_ref=<project-ref>&read_only=true&features=database,docs',
  },
});

const tools = await mcpClient.tools({
  schemas: createToolSchemas({
    features: ['database', 'docs'],
    projectScoped: true,
    readOnly: true,
  }),
});

[!NOTE] Este servidor não envia structuredContent nos resultados das ferramentas MCP. O AI SDK recorre à análise de JSON a partir do texto content.

Para mais informações, consulte Definição de Esquema e Saídas de Ferramentas Tipadas na documentação do AI SDK.

Outros servidores MCP

@supabase/mcp-server-postgrest

O servidor MCP PostgREST permite que você conecte seus próprios usuários ao seu aplicativo via API REST. Veja mais detalhes no README do projeto.

Recursos

• Model Context Protocol: Saiba mais sobre o MCP e suas capacidades.
• Do desenvolvimento à produção: Aprenda como promover alterações com segurança para ambientes de produção.

Para desenvolvedores

Veja CONTRIBUTING para detalhes sobre como contribuir com este projeto.

Licença

Este projeto está licenciado sob Apache 2.0. Veja o arquivo LICENSE para detalhes.