Self-Hosted Supabase MCP Server

Interactúa con instancias autoalojadas de Supabase para la gestión e introspección de bases de datos.

GitHub
1
Prueba este MCPPatrocinado

Documentación

Servidor MCP de Supabase Autoalojado

License: MIT smithery badge

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 autoalojadas. Cubre la brecha entre los clientes MCP (como extensiones de IDE) y tus proyectos de Supabase locales o alojados de forma privada, permitiendo la introspección de bases de datos, gestión e interacción directamente desde tu entorno de desarrollo.

Este servidor fue construido desde cero, tomando lecciones de la adaptación del servidor MCP oficial de la nube de Supabase, para proporcionar una implementación mínima y enfocada, adaptada al caso de uso autoalojado.

Propósito

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

  • Consultar esquemas y datos de bases de datos.
  • Gestionar migraciones de bases de datos.
  • Inspeccionar estadísticas y conexiones de bases de datos.
  • Gestionar usuarios de autenticación.
  • Interactuar con el almacenamiento de Supabase.
  • Generar definiciones de tipos.

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

Características (Herramientas implementadas)

El servidor expone las siguientes herramientas a los clientes MCP:

  • Esquema y migraciones
    • list_tables: Lista las tablas en los esquemas de la base de datos.
    • list_extensions: Lista las extensiones de PostgreSQL instaladas.
    • list_migrations: Lista las migraciones de Supabase aplicadas.
    • apply_migration: Aplica un script de migración SQL.
  • Operaciones y estadísticas de base de datos
    • execute_sql: Ejecuta una consulta SQL arbitraria (mediante RPC o conexión directa).
    • get_database_connections: Muestra las conexiones activas de la base de datos (pg_stat_activity).
    • get_database_stats: Recupera 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 de 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 de TypeScript a partir del esquema de la base de datos.
    • rebuild_hooks: Intenta reiniciar el trabajador pg_net (si se utiliza).
  • Gestión de usuarios de autenticación
    • list_auth_users: Lista 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 inseguro de contraseñas).
    • 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 de almacenamiento
    • list_storage_buckets: Lista todos los buckets de almacenamiento.
    • list_storage_objects: Lista los objetos dentro de un bucket específico.
  • Inspección en tiempo real
    • list_realtime_publications: Lista las publicaciones de PostgreSQL (a menudo supabase_realtime).

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

Configuración e instalación

Instalación mediante Smithery

Para instalar el Servidor MCP de Supabase Autoalojado para Claude Desktop automáticamente mediante Smithery:

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

Requisitos previos

  • Node.js (se recomienda la versión 18.x o posterior)
  • npm (generalmente incluido con Node.js)
  • Acceso a tu instancia de Supabase autoalojada (URL, claves, posiblemente cadena de conexión directa a la base de datos).

Pasos

  1. Clonar el repositorio: 
    git clone <repository-url>
cd self-hosted-supabase-mcp
  2. Instalar dependencias: 
    npm install
  3. Compilar 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 tu instancia de Supabase. Estos se pueden proporcionar mediante argumentos de línea de comandos o variables de entorno. Los argumentos de CLI tienen prioridad.

Requeridos:

  • --url <url> o SUPABASE_URL=<url>: La URL HTTP principal de tu proyecto de Supabase (por ejemplo, http://localhost:8000).
  • --anon-key <key> o SUPABASE_ANON_KEY=<key>: La clave anónima de tu proyecto de Supabase.

Opcionales (pero recomendados/requeridos para ciertas herramientas):

  • --service-key <key> o SUPABASE_SERVICE_ROLE_KEY=<key>: La clave de rol de servicio de tu proyecto de 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 tu base de datos de Supabase (por ejemplo, postgresql://postgres:password@localhost:5432/postgres). Requerida para herramientas que necesitan acceso directo a la base de datos o transacciones (apply_migration, herramientas de autenticación, herramientas de almacenamiento, consulta de pg_catalog, etc.).
  • --jwt-secret <secret> o SUPABASE_AUTH_JWT_SECRET=<secret>: El secreto JWT de tu proyecto de Supabase. Necesario para herramientas como verify_jwt_secret.
  • --tools-config <path>: Ruta a un archivo JSON que especifica qué herramientas habilitar (lista blanca). Si se omite, todas las herramientas definidas en el servidor están habilitadas. El archivo debe tener el formato {"enabledTools": ["tool_name_1", "tool_name_2"]}.

Notas importantes:

  • Función auxiliar execute_sql: Muchas herramientas dependen de una función public.execute_sql dentro de tu base de datos de Supabase para la ejecución segura y eficiente de SQL mediante RPC. El servidor intenta verificar esta función al inicio. Si falta y se proporcionan un service-key (o SUPABASE_SERVICE_ROLE_KEY) y un 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 pueden 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 el DATABASE_URL esté configurado para una conexión directa de pg.

Uso

Ejecuta el servidor usando 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 entrada/salida estándar (stdio) y está diseñado para ser invocado por una aplicación cliente MCP (por ejemplo, una extensión de 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 clientes

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

Importante:

  • Reemplaza los marcadores de posición como <your-supabase-url>, <your-anon-key>, <your-db-url>, <path-to-dist/index.js>, etc., con tus valores reales.
  • Asegúrate de que la ruta al archivo del servidor compilado (dist/index.js) sea correcta para tu sistema.
  • Ten cuidado al almacenar claves sensibles directamente en archivos de configuración, especialmente si se confirman en el control de versiones. Considera usar variables de entorno o métodos más seguros donde el cliente lo admita.

Cursor

  1. Crea o abre el archivo .cursor/mcp.json en la raíz de tu proyecto.

  2. Agrega 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 (Copilot)

VS Code Copilot permite usar variables de entorno pobladas mediante entradas solicitadas, lo cual es más seguro para las claves.

  1. Crea o abre el archivo .vscode/mcp.json en la raíz de tu proyecto.

  2. Agrega 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. Cuando uses Copilot Chat en modo Agente (@workspace), debería detectar el servidor. Se te pedirá que ingreses los detalles (URL, claves, ruta) cuando el servidor se invoque por primera vez.

Otros clientes (Windsurf, Cline, Claude)

Adapta la estructura de configuración mostrada para Cursor o la documentación oficial de Supabase, reemplazando el command y el 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>"
      ]
    }
  }
}

Consulta la documentación específica de cada cliente sobre dónde colocar el mcp.json o el archivo de configuración equivalente.

Desarrollo

  • Lenguaje: TypeScript
  • Compilación: tsc (Compilador de TypeScript)
  • Dependencias: Gestionadas mediante npm (package.json)
  • Bibliotecas principales: @supabase/supabase-js, pg (node-postgres), zod (validación), commander (argumentos de CLI), @modelcontextprotocol/sdk (marco de servidor MCP).

Licencia

Este proyecto está licenciado bajo la Licencia MIT. Consulta el archivo LICENSE para más detalles.