Servidor MCP de Supabase

Un servidor MCP con numerosas funciones que permite a Cursor y Windsurf interactuar de forma segura con las bases de datos de Supabase. Proporciona herramientas para la gestión de bases de datos, la ejecución de consultas SQL y el acceso a la API de gestión de Supabase con controles de seguridad integrados.

Tabla de contenido

✨ Características principales

• 💻 Compatible con Cursor, Windsurf, Cline y otros clientes MCP que admiten el protocolo stdio
• 🔐 Controlar los modos de solo lectura y lectura-escritura de la ejecución de consultas SQL
• 🔄 Manejo robusto de transacciones tanto para conexiones de bases de datos directas como agrupadas
• 💻 Administra tus proyectos de Supabase con la API de administración de Supabase
• 🧑‍💻 Administrar usuarios con métodos de administración de Supabase Auth a través del SDK de Python
• 🔨 Herramientas prediseñadas para ayudar a Cursor y Windsurf a trabajar con MCP de manera más efectiva
• 📦 Instalación y configuración extremadamente sencilla a través del administrador de paquetes (uv, pipx, etc.)

Empezando

Prerrequisitos

Para instalar el servidor se requiere lo siguiente en su sistema:

• Python 3.12+
• PostgresSQL 16+

Si planea instalarlo mediante uv , asegúrese de que esté instalado .

Instalación de PostgreSQL

⚠️ Importante : PostgreSQL debe instalarse ANTES de instalar las dependencias del proyecto, ya que psycopg2 requiere bibliotecas de desarrollo de PostgreSQL durante la compilación.

Sistema operativo Mac

Ventanas

• Descargue e instale PostgreSQL 16+ desde https://www.postgresql.org/download/windows/
• Asegúrese de que "Servidor PostgreSQL" y "Herramientas de línea de comandos" estén seleccionados durante la instalación

Paso 1. Instalación del servidor MCP

Desde la versión v0.2.0, introduje la compatibilidad con la instalación de paquetes. Puedes usar tu gestor de paquetes de Python preferido para instalar el servidor mediante:

Se recomienda pipx porque crea entornos aislados para cada paquete.

También puede instalar el servidor manualmente clonando el repositorio y ejecutando pipx install -editable desde el directorio raíz.

⚠️ Si encuentra problemas de compilación con psycopg2, es posible que falten paquetes de desarrollo de PostgreSQL. Consulte la información anterior.

Instalación desde la fuente

Si desea instalar desde la fuente, por ejemplo para desarrollo local:

Instalación mediante Smithery.ai

Por favor, informe cualquier problema con Smithery, ya que aún no lo he probado.

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

Paso 2. Configuración

Después de instalar el paquete, deberá configurar la conexión a la base de datos. El servidor admite instancias de Supabase locales y remotas.

Instancia local de Supabase (predeterminada)

El servidor está preconfigurado para conectarse a la instancia local de Supabase utilizando la configuración predeterminada:

• Host : 127.0.0.1:54322
• Password : postgres

💡 Siempre que no hayas modificado la configuración predeterminada y quieras conectarte a la instancia local, no necesitas configurar variables de entorno.

Instancia remota de Supabase

⚠️ ADVERTENCIA IMPORTANTE : No se admiten conexiones de agrupación de sesiones ni hay planes para hacerlo. Avísame si crees que es posible implementar esto en un servidor MCP.

Para proyectos remotos de Supabase, debe configurar:

• SUPABASE_PROJECT_REF - Su referencia de proyecto (se encuentra en la URL del proyecto)
• SUPABASE_DB_PASSWORD - Su contraseña de base de datos
• SUPABASE_REGION - (Opcional) El valor predeterminado es us-east-1
• SUPABASE_ACCESS_TOKEN - (Opcional) Para acceso a la API de administración

Puede obtener su SUPABASE_PROJECT_REF desde la URL del panel de su proyecto:

• https://supabase.com/dashboard/project/<supabase-project-ref>

El servidor admite todas las regiones de Supabase:

• us-west-1 - Oeste de EE. UU. (Norte de California)
• us-east-1 - Este de EE. UU. (Virginia del Norte) - predeterminado
• us-east-2 - Este de EE. UU. (Ohio)
• ca-central-1 - Canadá (Central)
• eu-west-1 - Oeste de la UE (Irlanda)
• eu-west-2 - Europa Occidental (Londres)
• eu-west-3 - Oeste de la UE (París)
• eu-central-1 - UE central (Frankfurt)
• eu-central-2 - Europa Central (Zúrich)
• eu-north-1 - Norte de la UE (Estocolmo)
• ap-south-1 - Sur de Asia (Bombay)
• ap-southeast-1 - Sudeste Asiático (Singapur)
• ap-northeast-1 - Noreste Asiático (Tokio)
• ap-northeast-2 - Noreste Asiático (Seúl)
• ap-southeast-2 - Oceanía (Sídney)
• sa-east-1 - América del Sur (São Paulo)

El método de configuración de MCP difiere entre Cursor y Windsurf. Lea la sección correspondiente para comprender cómo configurar la conexión.

Cursor

Desde la versión v0.46 hay dos formas de configurar servidores MCP en Cursor:

• por proyecto -> crea mcp.json en tu carpeta de proyecto/repositorio y .env para configurar la conexión
• globalmente -> cree un servidor MCP en Configuración y configúrelo usando .env , que solo es compatible con este servidor MCP

Puede crear un MCP específico para el proyecto mediante:

• creando una carpeta .cursor en su repositorio, si no existe
• creando o actualizando el archivo mcp.json con la siguiente configuración

⚠ Variables de entorno : Si configura el servidor MCP por proyecto, deberá crear un archivo .env para que se recopilen las configuraciones de conexión. No pude configurar mcp.json para que recopilen mis variables de entorno. 😔

Como alternativa, si desea configurar servidores MCP de forma global (es decir, no para cada proyecto), puede configurar los ajustes de conexión actualizando un archivo .env en una carpeta de configuración global ejecutando los siguientes comandos:

Esto crea la carpeta de configuración necesaria donde se almacenará el archivo de su entorno.

Esto abrirá el archivo .env. Una vez abierto, copie y pegue lo siguiente:

Verifique que el archivo exista: debería ver los valores que acaba de configurar:

Puede encontrar el archivo de configuración global:

• Ventanas: %APPDATA%/supabase-mcp/.env
• macOS/Linux: ~/.config/supabase-mcp/.env

Windsurf

Windsurf admite el formato .json estándar para la configuración de servidores MCP. Puede configurar el servidor en el archivo mcp_config.json:

💡 Encontrar la ruta del servidor :

• macOS/Linux: Ejecutar which supabase-mcp-server
• Windows: Ejecutar where supabase-mcp-server

Precedencia de configuración

El servidor busca la configuración en este orden:

1. Variables de entorno (máxima prioridad)
2. Archivo .env local en el directorio actual
3. Archivo de configuración global:
   • Ventanas: %APPDATA%/supabase-mcp/.env
   • macOS/Linux: ~/.config/supabase-mcp/.env
4. Configuración predeterminada (desarrollo local)

Paso 3. Ejecución del servidor MCP en Cursor/Windsurf

En general, cualquier cliente MCP que admita el protocolo stdio debería funcionar con este servidor MCP (Cline, por ejemplo), pero no lo he probado con nada excepto Cursor/Windsurf.

Cursor

Vaya a Configuración -> Características -> Servidores MCP y agregue un nuevo servidor con esta configuración:

Si la configuración es correcta, debería ver un indicador de punto verde y la cantidad de herramientas expuestas por el servidor.

Windsurf

Vaya a Cascade -> Haga clic en el icono del martillo -> Configurar -> Complete la configuración:

Si la configuración es correcta, debería ver un indicador de punto verde y un servidor supabase en el que se pueda hacer clic en la lista de servidores disponibles.

Solución de problemas

Aquí hay algunos consejos y trucos que podrían ayudarle:

• Instalación de depuración : ejecute supabase-mcp-server directamente desde la terminal para comprobar si funciona. Si no funciona, podría haber un problema con la instalación.
• Configuración del servidor MCP : si el paso anterior funciona correctamente, significa que el servidor está instalado y configurado correctamente. Siempre que haya proporcionado el comando correcto, el IDE debería poder conectarse. Asegúrese de proporcionar la ruta correcta al ejecutable del servidor.
• Variables de entorno : para conectarse a la base de datos correcta, asegúrese de configurar las variables de entorno en mcp_config.json o en el archivo .env ubicado en un directorio de configuración global ( ~/.config/supabase-mcp/.env en macOS/Linux o %APPDATA%\supabase-mcp\.env en Windows).
• Acceso a registros : el servidor MCP escribe registros detallados en un archivo:
  • Ubicación del archivo de registro:
    • macOS/Linux: ~/.local/share/supabase-mcp/mcp_server.log
    • Windows: %USERPROFILE%\.local\share\supabase-mcp\mcp_server.log
  • Los registros incluyen el estado de la conexión, los detalles de configuración y los resultados de la operación.
  • Ver registros usando cualquier editor de texto o comandos de terminal:
    # On macOS/Linux cat ~/.local/share/supabase-mcp/mcp_server.log # On Windows (PowerShell) Get-Content "$env:USERPROFILE\.local\share\supabase-mcp\mcp_server.log"

Si está atascado o alguna de las instrucciones anteriores es incorrecta, plantee un problema.

Inspector de MCP

Una herramienta muy útil para depurar problemas del servidor MCP es MCP Inspector. Si lo instalaste desde el código fuente, puedes ejecutar supabase-mcp-inspector desde el repositorio del proyecto, lo que ejecutará la instancia del inspector. Junto con los registros, esto te dará una visión general completa de lo que sucede en el servidor.

📝 Ejecutar supabase-mcp-inspector , si está instalado desde el paquete, no funciona correctamente. Lo validaré y lo solucionaré en la próxima versión.

Descripción general de las funciones

Herramientas de consulta de bases de datos

Desde la versión v0.3.0, el servidor admite operaciones de solo lectura y modificación de datos:

• Operaciones de lectura : consultas SELECT para recuperación de datos
• Lenguaje de manipulación de datos (DML) : operaciones INSERTAR, ACTUALIZAR, ELIMINAR para cambios de datos
• Lenguaje de definición de datos (DDL) : operaciones CREATE, ALTER, DROP para cambios de esquema*

*Nota: Las operaciones DDL requieren:

1. Modo de lectura y escritura habilitado a través de live_dangerously
2. Permisos suficientes para el rol de base de datos conectada

Manejo de transacciones

El servidor admite dos enfoques para ejecutar operaciones de escritura:

1. Control explícito de transacciones (recomendado):
   BEGIN; CREATE TABLE public.test_table (id SERIAL PRIMARY KEY, name TEXT); COMMIT;
2. Declaraciones individuales :
   CREATE TABLE public.test_table (id SERIAL PRIMARY KEY, name TEXT);

Para las operaciones DDL (CREATE/ALTER/DROP), la descripción de la herramienta guía apropiadamente a Cursor/Windsurft para utilizar el control de transacciones explícito con bloques BEGIN/COMMIT.

Tipos de conexión

Este servidor MCP utiliza:

• Conexión directa a la base de datos : al conectarse a una instancia local de Supabase
• Conexiones del agrupador de transacciones : al conectarse a una instancia remota de Supabase

Al conectarse mediante el agrupador de transacciones de Supabase, es posible que algunos patrones de transacciones complejos no funcionen correctamente. Para realizar cambios de esquema en estos entornos, utilice bloques de transacciones explícitos o considere usar las migraciones de Supabase o el editor SQL del panel de control.

Herramientas de base de datos disponibles:

• get_db_schemas : enumera todos los esquemas de base de datos con sus tamaños y recuentos de tablas
• get_tables : enumera todas las tablas de un esquema con sus tamaños, número de filas y metadatos
• get_table_schema : obtiene la estructura detallada de la tabla, incluidas columnas, claves y relaciones
• execute_sql_query : ejecuta consultas SQL sin procesar con soporte integral para todas las operaciones de PostgreSQL:
  • Admite todos los tipos de consultas (SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, etc.)
  • Maneja declaraciones de control de transacciones (BEGIN, COMMIT, ROLLBACK)
• Modos compatibles:
  • read-only : solo se permiten consultas de solo lectura (modo predeterminado)
  • read-write : se permiten todas las operaciones SQL cuando están habilitadas explícitamente
• Características de seguridad:
  • Se inicia en modo de solo lectura de forma predeterminada
  • Requiere cambio de modo explícito para operaciones de escritura
  • Se restablece automáticamente al modo de solo lectura después de las operaciones de escritura
  • Detección inteligente del estado de las transacciones para evitar errores
  • Validación de consultas SQL [TODO]

Herramientas de API de gestión

Desde la versión v0.3.0, el servidor admite el envío de solicitudes arbitrarias a la API de administración de Supabase con inyección automática de referencia de proyecto y control de modo de seguridad:

• Incluye las siguientes herramientas:
  • send_management_api_request para enviar solicitudes arbitrarias a la API de administración de Supabase, con inyección automática de referencia de proyecto y control de modo de seguridad
  • get_management_api_spec para obtener la especificación de API enriquecida con información de seguridad
  • get_management_api_safety_rules para obtener todas las reglas de seguridad, incluidas las operaciones bloqueadas e inseguras, con explicaciones legibles para humanos
  • live_dangerously para cambiar entre modos seguros e inseguros
• Características de seguridad:
  • Divide los métodos de API en categorías safe , unsafe y blocked según el riesgo de la operación.
  • Permite cambiar dinámicamente entre modos seguros e inseguros
  • Las operaciones bloqueadas (eliminar proyecto, eliminar base de datos) no están permitidas independientemente del modo

Herramientas de administración de autenticación

Planeaba añadir compatibilidad con los métodos del SDK de Python al servidor MCP. Tras considerarlo, decidí añadir solo compatibilidad con los métodos de administración de autenticación, ya que a menudo me encontraba creando manualmente usuarios de prueba, lo cual era propenso a errores y consumía mucho tiempo. Ahora puedo simplemente pedirle a Cursor que cree un usuario de prueba y lo hará sin problemas. Consulta la documentación completa de los métodos del SDK de administración de autenticación para saber qué puede hacer.

Desde la versión v0.3.6, el servidor admite el acceso directo a los métodos de administración de autenticación de Supabase a través del SDK de Python:

• Incluye las siguientes herramientas:
  • get_auth_admin_methods_spec para recuperar la documentación de todos los métodos de autenticación de administrador disponibles
  • call_auth_admin_method para invocar directamente los métodos de Auth Admin con un manejo adecuado de los parámetros
• Métodos admitidos:
  • get_user_by_id : recupera un usuario por su ID
  • list_users : Lista todos los usuarios con paginación
  • create_user : Crea un nuevo usuario
  • delete_user : Eliminar un usuario por su ID
  • invite_user_by_email : Envía un enlace de invitación al correo electrónico de un usuario
  • generate_link : Genera un enlace de correo electrónico para diversos fines de autenticación
  • update_user_by_id : Actualizar los atributos del usuario por ID
  • delete_factor : elimina un factor en un usuario (actualmente no implementado en el SDK)

¿Por qué utilizar Auth Admin SDK en lugar de consultas SQL sin procesar?

El SDK de administración de autenticación ofrece varias ventajas clave sobre la manipulación directa de SQL:

• Funcionalidad : Permite operaciones que no son posibles solo con SQL (invitaciones, enlaces mágicos, MFA)
• Precisión : Más confiable que crear y ejecutar consultas SQL sin procesar en esquemas de autenticación
• Simplicidad : ofrece métodos claros con validación adecuada y manejo de errores.
  • Formato de respuesta:
    • Todos los métodos devuelven objetos estructurados de Python en lugar de diccionarios sin formato
    • Se puede acceder a los atributos de objeto mediante la notación de puntos (por ejemplo, user.id en lugar de user["id"] )
  • Casos extremos y limitaciones:
    • Validación de UUID: muchos métodos requieren un formato UUID válido para los ID de usuario y devolverán errores de validación específicos
    • Configuración de correo electrónico: métodos como invite_user_by_email y generate_link requieren que el envío de correo electrónico esté configurado en su proyecto Supabase
    • Tipos de enlaces: al generar enlaces, los diferentes tipos de enlaces tienen diferentes requisitos:
      • Los enlaces signup no requieren que el usuario exista
      • Los enlaces magiclink y recovery requieren que el usuario ya exista en el sistema
    • Manejo de errores: El servidor proporciona mensajes de error detallados de la API de Supabase, que pueden diferir de la interfaz del panel de control
    • Disponibilidad del método: algunos métodos como delete_factor están expuestos en la API pero no están completamente implementados en el SDK

Hoja de ruta

• 📦 Instalación simplificada a través del administrador de paquetes - ✅ (v0.2.0)
• 🌎 Soporte para diferentes regiones de Supabase - ✅ (v0.2.2)
• 🎮 Acceso programático a la API de gestión de Supabase con controles de seguridad - ✅ (v0.3.0)
• 👷‍♂️ Consultas SQL de bases de datos de lectura y escritura con controles de seguridad - ✅ (v0.3.0)
• 🔄 Manejo robusto de transacciones tanto para conexiones directas como agrupadas - ✅ (v0.3.2)
• 🐍 Métodos y objetos de soporte disponibles en el SDK nativo de Python - ✅ (v0.3.6)
• 🔍 Validación de consultas SQL más sólida (operaciones de lectura vs. escritura)
• 📝 Versionado automático de consultas DDL(?)
• 🪵 Herramientas/recursos para acceder más fácilmente a bases de datos, registros de funciones edge (?)
• 👨‍💻 Integración CLI de Supabase (?)

Conectarse a los registros de Supabase

Estoy planeando investigar si es posible conectarse a los registros de la base de datos de Supabase, lo que podría ser útil para la depuración (si aún no es compatible).

¡Que lo disfrutes! ☺️