Provides tools for direct PostgreSQL database operations, including executing SQL queries, viewing database connections and statistics, listing extensions, and querying system catalogs.
Enables interaction with self-hosted Supabase instances, providing tools for database introspection, SQL query execution, schema management, migrations, auth user management, storage bucket operations, and TypeScript type generation.
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.
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:
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.
El servidor expone las siguientes herramientas a los clientes MCP:
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.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_* ).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.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).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).list_storage_buckets : enumera todos los depósitos de almacenamiento.list_storage_objects : enumera los objetos dentro de un depósito específico.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).
Para instalar automáticamente el servidor MCP autohospedado Supabase para Claude Desktop a través de Smithery :
dist .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"]} .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.auth , storage ) o catálogos del sistema ( pg_catalog ) generalmente requieren que DATABASE_URL esté configurado para una conexión pg directa.Ejecute el servidor utilizando Node.js, proporcionando la configuración necesaria:
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.
A continuación se muestran ejemplos de cómo configurar clientes MCP populares para utilizar este servidor autohospedado.
Importante:
<your-supabase-url> , <your-anon-key> , <your-db-url> , <path-to-dist/index.js> etc., con sus valores reales.dist/index.js ) sea correcta para su sistema..cursor/mcp.json en la raíz de su proyecto.VS Code Copilot permite utilizar variables de entorno rellenadas mediante entradas solicitadas, lo que es más seguro para las claves.
.vscode/mcp.json en la raíz de su proyecto.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:
Consulte la documentación específica de cada cliente sobre dónde colocar el archivo de configuración mcp.json o equivalente.
tsc (compilador de TypeScript)npm ( package.json )@supabase/supabase-js , pg (node-postgres), zod (validación), commander (argumentos CLI), @modelcontextprotocol/sdk (marco de servidor MCP).Este proyecto está licenciado bajo la Licencia MIT. Consulte el archivo de LICENCIA para más detalles.
You must be authenticated.
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Un servidor de protocolo que permite la interacción con instancias de Supabase autohospedadas directamente desde entornos de desarrollo, lo que permite la introspección de la base de datos, la gestión de migraciones, la autenticación de usuarios y el almacenamiento a través de clientes MCP como extensiones IDE.