Supabase

Servidor MCP do Supabase

Um servidor do Protocolo de Contexto de Modelo (MCP) para interagir com bancos de dados do Supabase. Este servidor fornece ferramentas para consultar tabelas e gerar tipos TypeScript por meio da interface MCP.

Recursos

• Consultar Tabelas: Execute consultas em qualquer tabela com suporte para:

  • Seleção de esquema
  • Filtragem de colunas
  • Cláusulas WHERE com múltiplos operadores
  • Paginação
  • Tratamento de erros

• Geração de Tipos: Gere tipos TypeScript para o seu banco de dados:

  • Suporte para qualquer esquema (public, auth, api, etc.)
  • Funciona com projetos Supabase locais e remotos
  • Saída direta no console
  • Detecção automática de referência do projeto

Pré-requisitos

1. Node.js (v16 ou superior)
2. Um projeto Supabase (local ou hospedado)
3. Supabase CLI (para geração de tipos)

Instalação

1. Clone o repositório:

git clone https://github.com/yourusername/supabase-mcp-server.git
cd supabase-mcp-server

2. Instale as dependências:

npm install

3. Instale o Supabase CLI (necessário para geração de tipos):

# Using npm
npm install -g supabase

# Or using Homebrew on macOS
brew install supabase/tap/supabase

Configuração

1. Obtenha suas credenciais do Supabase:

   • Para projetos hospedados:

     1. Acesse o painel do seu projeto Supabase
     2. Navegue até Project Settings > API
     3. Copie a URL do projeto e a chave service_role (NÃO a chave anon)

   • Para projetos locais:

     1. Inicie sua instância local do Supabase
     2. Use a URL local (normalmente http://localhost:54321)
     3. Use sua chave service_role local

2. Configure as variáveis de ambiente:

# Create a .env file (this will be ignored by git)
echo "SUPABASE_URL=your_project_url
SUPABASE_KEY=your_service_role_key" > .env

3. Compile o servidor:

npm run build

Integração com Claude Desktop

1. Abra as configurações do Claude Desktop:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Adicione a configuração do servidor:

{
  "mcpServers": {
    "supabase": {
      "command": "node",
      "args": ["/absolute/path/to/supabase-mcp-server/build/index.js"],
      "env": {
        "SUPABASE_URL": "your_project_url",
        "SUPABASE_KEY": "your_service_role_key"
      }
    }
  }
}

Integração com a Extensão do VSCode

1. Abra as configurações do VSCode:

   • macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
   • Windows: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
   • Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

2. Adicione a configuração do servidor (mesmo formato do Claude Desktop).

Exemplos de Uso

Consultando Tabelas

// Query with schema selection and where clause
<use_mcp_tool>
<server_name>supabase</server_name>
<tool_name>query_table</tool_name>
<arguments>
{
  "schema": "public",
  "table": "users",
  "select": "id,name,email",
  "where": [
    {
      "column": "is_active",
      "operator": "eq",
      "value": true
    }
  ]
}
</arguments>
</use_mcp_tool>

Gerando Tipos

// Generate types for public schema
<use_mcp_tool>
<server_name>supabase</server_name>
<tool_name>generate_types</tool_name>
<arguments>
{
  "schema": "public"
}
</arguments>
</use_mcp_tool>

Ferramentas Disponíveis

query_table

Consulte uma tabela específica com seleção de esquema e suporte a cláusula WHERE.

Parâmetros:

• schema (opcional): Esquema do banco de dados (padrão: public)
• table (obrigatório): Nome da tabela a ser consultada
• select (opcional): Lista de colunas separadas por vírgula
• where (opcional): Matriz de condições com:
  • column: Nome da coluna
  • operator: Um de: eq, neq, gt, gte, lt, lte, like, ilike, is
  • value: Valor para comparação

generate_types

Gere tipos TypeScript para o esquema do banco de dados do Supabase.

Parâmetros:

• schema (opcional): Esquema do banco de dados (padrão: public)

Solução de Problemas

Problemas com Geração de Tipos

1. Garanta que o Supabase CLI esteja instalado:

supabase --version

2. Para projetos locais:

   • Certifique-se de que sua instância local do Supabase esteja em execução
   • Verifique se a chave service_role está correta

3. Para projetos hospedados:

   • Confirme se a referência do projeto está correta (extraída da URL)
   • Verifique se você está usando a chave service_role, não a chave anon

Problemas com Consultas

1. Verifique os nomes do esquema e da tabela
2. Confirme os nomes das colunas nas cláusulas select e where
3. Garanta que sua chave service_role tenha as permissões necessárias

Contribuindo

1. Faça um fork do repositório
2. Crie sua branch de recurso: git checkout -b feature/my-feature
3. Faça commit das suas alterações: git commit -am 'Add my feature'
4. Envie para a branch: git push origin feature/my-feature
5. Envie um pull request

Licença

Licença MIT - consulte o arquivo LICENSE para obter detalhes