Servidor MCP Supabase autoalojado

Descripción general

Este proyecto proporciona un servidor de Protocolo de Contexto de Modelo (MCP) diseñado específicamente para interactuar con instancias de Supabase alojadas en el propio servidor . Une los clientes MCP (como extensiones de IDE) y sus proyectos de Supabase locales o privados, lo que permite la introspección, la gestión y la interacción con la base de datos directamente desde su entorno de desarrollo.

Este servidor se construyó desde cero, aprovechando las lecciones aprendidas al adaptar el servidor MCP en la nube oficial de Supabase, para brindar una implementación mínima y enfocada, adaptada al caso de uso autohospedado.

Related MCP server: Self-Hosted Supabase MCP Server

Objetivo

El objetivo principal de este servidor es permitir que los desarrolladores que utilizan instalaciones de Supabase autohospedadas aprovechen las herramientas basadas en MCP para tareas como:

• Consulta de esquemas y datos de bases de datos.

• Gestión de migraciones de bases de datos.

• Inspeccionar las estadísticas y conexiones de la base de datos.

• Gestión de usuarios de autenticación.

• Interactuando con Supabase Storage.

• Generando definiciones de tipos.

Evita las complejidades del servidor en la nube oficial relacionadas con la gestión de múltiples proyectos y las API específicas de la nube, ofreciendo una experiencia optimizada para entornos autohospedados de un solo proyecto.

Características (herramientas implementadas)

El servidor expone las siguientes herramientas a los clientes MCP:

• Esquema y migraciones

  • list_tables : enumera las tablas en los esquemas de la base de datos.

  • list_extensions : enumera las extensiones PostgreSQL instaladas.

  • list_migrations : enumera las migraciones de Supabase aplicadas.

  • apply_migration : aplica un script de migración SQL.

• Operaciones y estadísticas de bases de datos

  • execute_sql : ejecuta una consulta SQL arbitraria (a través de RPC o conexión directa).

  • get_database_connections : muestra las conexiones de base de datos activas ( pg_stat_activity ).

  • get_database_stats : recupera las estadísticas de la base de datos ( pg_stat_* ).

• Configuración del proyecto y claves

  • get_project_url : Devuelve la URL de Supabase configurada.

  • get_anon_key : Devuelve la clave anónima de Supabase configurada.

  • get_service_key : Devuelve la clave de rol de servicio Supabase configurada (si se proporciona).

  • verify_jwt_secret : comprueba si el secreto JWT está configurado y devuelve una vista previa.

• Herramientas de desarrollo y extensión

  • generate_typescript_types : genera tipos TypeScript a partir del esquema de base de datos.

  • rebuild_hooks : intenta reiniciar el trabajador pg_net (si se utiliza).

• Gestión de usuarios autorizados

  • list_auth_users : enumera los usuarios de auth.users .

  • get_auth_user : recupera detalles de un usuario específico.

  • create_auth_user : crea un nuevo usuario (requiere acceso directo a la base de datos, manejo de contraseñas inseguro).

  • delete_auth_user : elimina un usuario (requiere acceso directo a la base de datos).

  • update_auth_user : actualiza los detalles del usuario (requiere acceso directo a la base de datos, manejo inseguro de contraseñas).

• Información sobre almacenamiento

  • list_storage_buckets : enumera todos los depósitos de almacenamiento.

  • list_storage_objects : enumera los objetos dentro de un depósito específico.

• Inspección en tiempo real

  • list_realtime_publications : enumera las publicaciones de PostgreSQL (a menudo supabase_realtime ).

(Nota: get_logs se planeó inicialmente, pero se omitió debido a complejidades de implementación en un entorno auto hospedado).

Configuración e instalación

Instalación mediante herrería

Para instalar automáticamente el servidor MCP autohospedado Supabase para Claude Desktop a través de Smithery :

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

Prerrequisitos

• Node.js (versión 18.x o posterior recomendada)

• npm (generalmente incluido con Node.js)

• Acceso a su instancia de Supabase autohospedada (URL, claves, cadena de conexión a base de datos potencialmente directa).

Pasos

1. Clonar el repositorio:

   git clone <repository-url>
   cd self-hosted-supabase-mcp

2. Instalar dependencias:

   npm install

3. Construir el proyecto:

   npm run build

   Esto compila el código TypeScript a JavaScript en el directorio dist .

Configuración

El servidor requiere detalles de configuración para su instancia de Supabase. Estos pueden proporcionarse mediante argumentos de la línea de comandos o variables de entorno. Los argumentos de la CLI tienen prioridad.

Requerido:

• --url <url> o SUPABASE_URL=<url> : La URL HTTP principal de su proyecto Supabase (por ejemplo, http://localhost:8000 ).

• --anon-key <key> o SUPABASE_ANON_KEY=<key> : La clave anónima de su proyecto Supabase.

Opcional (pero recomendado/obligatorio para ciertas herramientas):

• --service-key <key> o SUPABASE_SERVICE_ROLE_KEY=<key> : La clave del rol de servicio de su proyecto Supabase. Necesaria para operaciones que requieren privilegios elevados, como intentar crear automáticamente la función auxiliar execute_sql si no existe.

• --db-url <url> o DATABASE_URL=<url> : La cadena de conexión directa de PostgreSQL para su base de datos Supabase (p. ej., postgresql://postgres:password@localhost:5432/postgres ). Necesaria para herramientas que requieren acceso directo a la base de datos o transacciones ( apply_migration , herramientas de autenticación, herramientas de almacenamiento, consultas pg_catalog , etc.).

• --jwt-secret <secret> o SUPABASE_AUTH_JWT_SECRET=<secret> : El secreto JWT de su proyecto Supabase. Necesario para herramientas como verify_jwt_secret .

• --tools-config <path> : Ruta a un archivo JSON que especifica las herramientas que se habilitarán (lista blanca). Si se omite, se habilitan todas las herramientas definidas en el servidor. El archivo debe tener el formato {"enabledTools": ["tool_name_1", "tool_name_2"]} .

Notas importantes:

• Función auxiliar execute_sql : Muchas herramientas utilizan la función public.execute_sql de su base de datos Supabase para una ejecución SQL segura y eficiente mediante RPC. El servidor intenta comprobar esta función al iniciarse. Si no está presente y se proporcionan una service-key (o SUPABASE_SERVICE_ROLE_KEY ) y db-url (o DATABASE_URL ), intentará crear la función y otorgar los permisos necesarios. Si la creación falla o no se proporcionan las claves, las herramientas que dependen únicamente de RPC podrían fallar.

• Acceso directo a la base de datos: las herramientas que interactúan directamente con esquemas privilegiados ( auth , storage ) o catálogos del sistema ( pg_catalog ) generalmente requieren que DATABASE_URL esté configurado para una conexión pg directa.

Uso

Ejecute el servidor utilizando Node.js, proporcionando la configuración necesaria:

# 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 ...

El servidor se comunica mediante la entrada/salida estándar (stdio) y está diseñado para ser invocado por una aplicación cliente MCP (por ejemplo, una extensión IDE como Cursor). El cliente se conectará al flujo stdio del servidor para listar y llamar a las herramientas disponibles.

Ejemplos de configuración de cliente

A continuación se muestran ejemplos de cómo configurar clientes MCP populares para utilizar este servidor autohospedado.

Importante:

• Reemplace los marcadores de posición como <your-supabase-url> , <your-anon-key> , <your-db-url> , <path-to-dist/index.js> etc., con sus valores reales.

• Asegúrese de que la ruta al archivo del servidor compilado ( dist/index.js ) sea correcta para su sistema.

• Tenga cuidado al almacenar claves confidenciales directamente en archivos de configuración, especialmente si están asignadas al control de versiones. Considere usar variables de entorno o métodos más seguros si el cliente lo admite.

Cursor

1. Cree o abra el archivo .cursor/mcp.json en la raíz de su proyecto.

2. Agregue la siguiente configuración:

   {
     "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 (Copiloto)

VS Code Copilot permite utilizar variables de entorno rellenadas mediante entradas solicitadas, lo que es más seguro para las claves.

1. Cree o abra el archivo .vscode/mcp.json en la raíz de su proyecto.

2. Agregue la siguiente configuración:

   {
     "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. Al usar Copilot Chat en modo Agente (@workspace), debería detectar el servidor. Se le solicitará que ingrese los detalles (URL, claves, ruta) al iniciar el servidor por primera vez.

Otros clientes (Windsurf, Cline, Claude)

Adapte la estructura de configuración que se muestra para Cursor o la documentación oficial de Supabase, reemplazando el command y args con el comando node y los argumentos para este servidor, similar al ejemplo de 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 la documentación específica de cada cliente sobre dónde colocar el archivo de configuración mcp.json o equivalente.

Desarrollo

• Lenguaje: TypeScript

• Compilación: tsc (compilador de TypeScript)

• Dependencias: administradas a través de npm ( package.json )

• Bibliotecas principales: @supabase/supabase-js , pg (node-postgres), zod (validación), commander (argumentos CLI), @modelcontextprotocol/sdk (marco de servidor MCP).

Licencia

Este proyecto está licenciado bajo la Licencia MIT. Consulte el archivo de LICENCIA para más detalles.