Self-Hosted Supabase MCP Server

Interaja com instâncias auto-hospedadas do Supabase para gerenciamento e introspecção de banco de dados.

GitHub
1
Experimente este MCPPatrocinado

Documentação

Servidor MCP Supabase Auto-hospedado

License: MIT smithery badge

Visão Geral

Este projeto fornece um servidor Model Context Protocol (MCP) projetado especificamente para interagir com instâncias Supabase auto-hospedadas. Ele preenche a lacuna entre clientes MCP (como extensões de IDE) e seus projetos Supabase locais ou hospedados privadamente, permitindo introspecção de banco de dados, gerenciamento e interação diretamente do seu ambiente de desenvolvimento.

Este servidor foi construído do zero, aproveitando lições aprendidas ao adaptar o servidor MCP oficial da nuvem Supabase, para fornecer uma implementação mínima e focada, adaptada ao caso de uso auto-hospedado.

Propósito

O objetivo principal deste servidor é permitir que desenvolvedores que usam instalações Supabase auto-hospedadas aproveitem ferramentas baseadas em MCP para tarefas como:

  • Consultar esquemas e dados do banco de dados.
  • Gerenciar migrações de banco de dados.
  • Inspecionar estatísticas e conexões do banco de dados.
  • Gerenciar usuários de autenticação.
  • Interagir com o Supabase Storage.
  • Gerar definições de tipos.

Ele evita as complexidades do servidor oficial da nuvem relacionadas ao gerenciamento de múltiplos projetos e APIs específicas da nuvem, oferecendo uma experiência simplificada para ambientes auto-hospedados de projeto único.

Recursos (Ferramentas Implementadas)

O servidor expõe as seguintes ferramentas aos clientes MCP:

  • Esquema e Migrações
    • list_tables: Lista tabelas nos esquemas do banco de dados.
    • list_extensions: Lista extensões PostgreSQL instaladas.
    • list_migrations: Lista migrações Supabase aplicadas.
    • apply_migration: Aplica um script de migração SQL.
  • Operações e Estatísticas do Banco de Dados
    • execute_sql: Executa uma consulta SQL arbitrária (via RPC ou conexão direta).
    • get_database_connections: Mostra conexões ativas do banco de dados (pg_stat_activity).
    • get_database_stats: Recupera estatísticas do banco de dados (pg_stat_*).
  • Configuração do Projeto e Chaves
    • get_project_url: Retorna a URL Supabase configurada.
    • get_anon_key: Retorna a chave anônima Supabase configurada.
    • get_service_key: Retorna a chave de função de serviço Supabase configurada (se fornecida).
    • verify_jwt_secret: Verifica se o segredo JWT está configurado e retorna uma prévia.
  • Ferramentas de Desenvolvimento e Extensão
    • generate_typescript_types: Gera tipos TypeScript a partir do esquema do banco de dados.
    • rebuild_hooks: Tenta reiniciar o worker pg_net (se usado).
  • Gerenciamento de Usuários de Autenticação
    • list_auth_users: Lista usuários de auth.users.
    • get_auth_user: Recupera detalhes de um usuário específico.
    • create_auth_user: Cria um novo usuário (Requer acesso direto ao banco de dados, tratamento inseguro de senha).
    • delete_auth_user: Exclui um usuário (Requer acesso direto ao banco de dados).
    • update_auth_user: Atualiza detalhes do usuário (Requer acesso direto ao banco de dados, tratamento inseguro de senha).
  • Insights de Armazenamento
    • list_storage_buckets: Lista todos os buckets de armazenamento.
    • list_storage_objects: Lista objetos dentro de um bucket específico.
  • Inspeção em Tempo Real
    • list_realtime_publications: Lista publicações PostgreSQL (frequentemente supabase_realtime).

(Nota: get_logs foi inicialmente planejado, mas pulado devido a complexidades de implementação em um ambiente auto-hospedado).

Configuração e Instalação

Instalação via Smithery

Para instalar o Servidor MCP Supabase Auto-hospedado para Claude Desktop automaticamente via Smithery:

npx -y @smithery/cli install @HenkDz/selfhosted-supabase-mcp --client claude

Pré-requisitos

  • Node.js (versão 18.x ou posterior recomendada)
  • npm (geralmente incluído com Node.js)
  • Acesso à sua instância Supabase auto-hospedada (URL, chaves, potencialmente string de conexão direta ao banco de dados).

Passos

  1. Clone o repositório: 
    git clone <repository-url>
cd self-hosted-supabase-mcp
  2. Instale as dependências: 
    npm install
  3. Compile o projeto: 
    npm run build
    Isso compila o código TypeScript para JavaScript no diretório dist.

Configuração

O servidor requer detalhes de configuração para sua instância Supabase. Eles podem ser fornecidos via argumentos de linha de comando ou variáveis de ambiente. Os argumentos de CLI têm precedência.

Obrigatório:

  • --url <url> ou SUPABASE_URL=<url>: A URL HTTP principal do seu projeto Supabase (por exemplo, http://localhost:8000).
  • --anon-key <key> ou SUPABASE_ANON_KEY=<key>: A chave anônima do seu projeto Supabase.

Opcional (mas Recomendado/Obrigatório para certas ferramentas):

  • --service-key <key> ou SUPABASE_SERVICE_ROLE_KEY=<key>: A chave de função de serviço do seu projeto Supabase. Necessária para operações que exigem privilégios elevados, como tentar criar automaticamente a função auxiliar execute_sql se ela não existir.
  • --db-url <url> ou DATABASE_URL=<url>: A string de conexão PostgreSQL direta para seu banco de dados Supabase (por exemplo, postgresql://postgres:password@localhost:5432/postgres). Necessária para ferramentas que exigem acesso direto ao banco de dados ou transações (apply_migration, ferramentas de Auth, ferramentas de Storage, consulta a pg_catalog, etc.).
  • --jwt-secret <secret> ou SUPABASE_AUTH_JWT_SECRET=<secret>: O segredo JWT do seu projeto Supabase. Necessário para ferramentas como verify_jwt_secret.
  • --tools-config <path>: Caminho para um arquivo JSON especificando quais ferramentas habilitar (lista de permissões). Se omitido, todas as ferramentas definidas no servidor são habilitadas. O arquivo deve ter o formato {"enabledTools": ["tool_name_1", "tool_name_2"]}.

Notas Importantes:

  • Função Auxiliar execute_sql: Muitas ferramentas dependem de uma função public.execute_sql dentro do seu banco de dados Supabase para execução SQL segura e eficiente via RPC. O servidor tenta verificar essa função na inicialização. Se ela estiver ausente e um service-key (ou SUPABASE_SERVICE_ROLE_KEY) e db-url (ou DATABASE_URL) forem fornecidos, ele tentará criar a função e conceder as permissões necessárias. Se a criação falhar ou as chaves não forem fornecidas, as ferramentas que dependem exclusivamente de RPC podem falhar.
  • Acesso Direto ao Banco de Dados: Ferramentas que interagem diretamente com esquemas privilegiados (auth, storage) ou catálogos do sistema (pg_catalog) geralmente exigem que o DATABASE_URL seja configurado para uma conexão pg direta.

Uso

Execute o servidor usando Node.js, fornecendo a configuração necessária:

# Using CLI arguments (example)
node dist/index.js --url http://localhost:8000 --anon-key <your-anon-key> --db-url postgresql://postgres:password@localhost:5432/postgres [--service-key <your-service-key>]

# Example with tool whitelisting via config file
node dist/index.js --url http://localhost:8000 --anon-key <your-anon-key> --tools-config ./mcp-tools.json

# Or configure using environment variables and run:
# export SUPABASE_URL=http://localhost:8000
# export SUPABASE_ANON_KEY=<your-anon-key>
# export DATABASE_URL=postgresql://postgres:password@localhost:5432/postgres
# export SUPABASE_SERVICE_ROLE_KEY=<your-service-key>
# The --tools-config option MUST be passed as a CLI argument if used
node dist/index.js

# Using npm start script (if configured in package.json to pass args/read env)
npm start -- --url ... --anon-key ...

O servidor se comunica via entrada/saída padrão (stdio) e é projetado para ser invocado por um aplicativo cliente MCP (por exemplo, uma extensão de IDE como Cursor). O cliente se conectará ao fluxo stdio do servidor para listar e chamar as ferramentas disponíveis.

Exemplos de Configuração de Cliente

Abaixo estão exemplos de como configurar clientes MCP populares para usar este servidor auto-hospedado.

Importante:

  • Substitua espaços reservados como <your-supabase-url>, <your-anon-key>, <your-db-url>, <path-to-dist/index.js> etc., pelos seus valores reais.
  • Certifique-se de que o caminho para o arquivo do servidor compilado (dist/index.js) esteja correto para o seu sistema.
  • Tenha cuidado ao armazenar chaves sensíveis diretamente em arquivos de configuração, especialmente se forem commitadas no controle de versão. Considere usar variáveis de ambiente ou métodos mais seguros onde suportados pelo cliente.

Cursor

  1. Crie ou abra o arquivo .cursor/mcp.json na raiz do seu projeto.

  2. Adicione a seguinte configuração:

    {
  "mcpServers": {
    "selfhosted-supabase": { 
      "command": "node",
      "args": [
        "<path-to-dist/index.js>", // e.g., "F:/Projects/mcp-servers/self-hosted-supabase-mcp/dist/index.js"
        "--url",
        "<your-supabase-url>", // e.g., "http://localhost:8000"
        "--anon-key",
        "<your-anon-key>",
        // Optional - Add these if needed by the tools you use
        "--service-key",
        "<your-service-key>",
        "--db-url",
        "<your-db-url>", // e.g., "postgresql://postgres:password@host:port/postgres"
        "--jwt-secret",
        "<your-jwt-secret>",
        // Optional - Whitelist specific tools
        "--tools-config",
        "<path-to-your-mcp-tools.json>" // e.g., "./mcp-tools.json"
      ]
    }
  }
}

Visual Studio Code (Copilot)

O VS Code Copilot permite usar variáveis de ambiente preenchidas via entradas solicitadas, o que é mais seguro para chaves.

  1. Crie ou abra o arquivo .vscode/mcp.json na raiz do seu projeto.

  2. Adicione a seguinte configuração:

    {
  "inputs": [
    { "type": "promptString", "id": "sh-supabase-url", "description": "Self-Hosted Supabase URL", "default": "http://localhost:8000" },
    { "type": "promptString", "id": "sh-supabase-anon-key", "description": "Self-Hosted Supabase Anon Key", "password": true },
    { "type": "promptString", "id": "sh-supabase-service-key", "description": "Self-Hosted Supabase Service Key (Optional)", "password": true, "required": false },
    { "type": "promptString", "id": "sh-supabase-db-url", "description": "Self-Hosted Supabase DB URL (Optional)", "password": true, "required": false },
    { "type": "promptString", "id": "sh-supabase-jwt-secret", "description": "Self-Hosted Supabase JWT Secret (Optional)", "password": true, "required": false },
    { "type": "promptString", "id": "sh-supabase-server-path", "description": "Path to self-hosted-supabase-mcp/dist/index.js" },
    { "type": "promptString", "id": "sh-supabase-tools-config", "description": "Path to tools config JSON (Optional, e.g., ./mcp-tools.json)", "required": false }
  ],
  "servers": {
    "selfhosted-supabase": {
      "command": "node",
      // Arguments are passed via environment variables set below OR direct args for non-env options
      "args": [
        "${input:sh-supabase-server-path}",
        // Use direct args for options not easily map-able to standard env vars like tools-config
        // Check if tools-config input is provided before adding the argument
        ["--tools-config", "${input:sh-supabase-tools-config}"] 
        // Alternatively, pass all as args if simpler:
        // "--url", "${input:sh-supabase-url}",
        // "--anon-key", "${input:sh-supabase-anon-key}",
        // ... etc ... 
       ],
      "env": {
        "SUPABASE_URL": "${input:sh-supabase-url}",
        "SUPABASE_ANON_KEY": "${input:sh-supabase-anon-key}",
        "SUPABASE_SERVICE_ROLE_KEY": "${input:sh-supabase-service-key}",
        "DATABASE_URL": "${input:sh-supabase-db-url}",
        "SUPABASE_AUTH_JWT_SECRET": "${input:sh-supabase-jwt-secret}"
        // The server reads these environment variables as fallbacks if CLI args are missing
      }
    }
  }
}

  3. Quando você usar o Copilot Chat no modo Agente (@workspace), ele deve detectar o servidor. Você será solicitado a inserir os detalhes (URL, chaves, caminho) quando o servidor for invocado pela primeira vez.

Outros Clientes (Windsurf, Cline, Claude)

Adapte a estrutura de configuração mostrada para Cursor ou a documentação oficial do Supabase, substituindo o command e args pelo comando node e os argumentos para este servidor, semelhante ao exemplo do Cursor:

{
  "mcpServers": {
    "selfhosted-supabase": { 
      "command": "node",
      "args": [
        "<path-to-dist/index.js>", 
        "--url", "<your-supabase-url>", 
        "--anon-key", "<your-anon-key>", 
        // Optional args...
        "--service-key", "<your-service-key>", 
        "--db-url", "<your-db-url>", 
        "--jwt-secret", "<your-jwt-secret>",
        // Optional tools config
        "--tools-config", "<path-to-your-mcp-tools.json>"
      ]
    }
  }
}

Consulte a documentação específica de cada cliente sobre onde colocar o mcp.json ou arquivo de configuração equivalente.

Desenvolvimento

  • Linguagem: TypeScript
  • Compilação: tsc (Compilador TypeScript)
  • Dependências: Gerenciadas via npm (package.json)
  • Bibliotecas Principais: @supabase/supabase-js, pg (node-postgres), zod (validação), commander (argumentos CLI), @modelcontextprotocol/sdk (framework de servidor MCP).

Licença

Este projeto é licenciado sob a Licença MIT. Consulte o arquivo LICENSE para detalhes.