Supabase MCP Server
Servidor MCP oficial de Supabase: tus proyectos al alcance de Cursor, Claude y otros asistentes, con modo de solo lectura y acotado por proyecto.
Fuente: Supabase MCP Server (repositorio oficial) · Oficial · Mantiene Supabase · Licencia Apache-2.0 · Ver original en github.com
Ficha técnica
- Organización
- Supabase (se abre en una pestaña nueva)
- Transporte
- HTTP (servidor alojado por Supabase); endpoint propio con el paquete npm
- Clientes compatibles
- Cursor
- Claude
- Windsurf
- Instalación
https://mcp.supabase.com/mcp
Qué es y qué expone
Supabase MCP Server es el servidor MCP oficial de Supabase: conecta tus proyectos de Supabase con Cursor, Claude, Windsurf y otros asistentes de IA. Según su README, MCP estandariza cómo los LLM hablan con servicios externos como Supabase, y el servidor conecta los asistentes de IA directamente con tu proyecto para que hagan tareas como gestionar tablas, obtener la configuración y consultar datos.
Sus herramientas se agrupan en funcionalidades: account, branching, database, debugging, development, docs, feedback, functions, notebooks y storage. Por defecto se activan todas menos notebooks y storage. Cubren la cuenta y los proyectos, las ramas de desarrollo, la base de datos Postgres, los logs y avisos, las Edge Functions y el almacenamiento.
El servidor se publica en npm como @supabase/mcp-server-supabase, y el repositorio, con licencia Apache 2.0, incluye además @supabase/mcp-server-postgrest, un servidor MCP de PostgREST que permite conectar a los usuarios de tu app con ella mediante la API REST.
Valoración de KIRELEN: encaja con equipos que desarrollan sobre Supabase desde un editor con agente y quieren consultar el esquema, aplicar migraciones o revisar logs sin salir de él.
Qué problema resuelve
El servidor conecta los asistentes de IA directamente con tu proyecto de Supabase, de modo que tareas como gestionar tablas, obtener la configuración o consultar datos se piden al asistente en lugar de hacerse a mano en el panel.
Algunas herramientas lo muestran bien. list_projects lista los proyectos de Supabase del usuario y sirve para descubrir el ID del proyecto en el que trabaja. generate_typescript_types genera los tipos de TypeScript del proyecto. get_advisors devuelve los avisos del proyecto para detectar vulnerabilidades de seguridad, mejoras de rendimiento o problemas de salud, y conviene ejecutarlo con regularidad, sobre todo tras cambios DDL en la base de datos, porque detecta, por ejemplo, políticas RLS que faltan. search_docs busca en la documentación de Supabase con GraphQL, y su descripción pide usarla aunque el agente crea saber la respuesta, porque la documentación se actualiza continuamente.
Para los cambios de esquema, el repositorio documenta un flujo con ramas de desarrollo: una rama permite experimentar con cambios de esquema reduciendo el riesgo de pérdida de datos, caídas o incompatibilidades entre la app y la base de datos de producción.
Cómo funciona
Servidor alojado e inicio de sesión
La mayoría de los clientes MCP solo necesitan la configuración que aparece en «Configuración»: el tipo http y la URL del servidor de Supabase. Durante la configuración, el cliente MCP pide iniciar sesión en Supabase, y hay que elegir la organización que contiene el proyecto con el que quieres trabajar. En el panel de Supabase, la pestaña de conexión MCP genera además una URL de MCP personalizada para tu proyecto. Si tu cliente MCP no aparece en la documentación, copias esa información en el formato que espere (JSON, YAML u otro).
Acotar el servidor
Sin más opciones, el servidor tiene acceso a todas las organizaciones y proyectos del usuario. Con el ID de un proyecto (project_ref) queda acotado a él: las herramientas dejan de pedir project_id y se excluyen las de nivel de cuenta. Con read_only=true, las consultas a la base de datos se ejecutan en modo de solo lectura y el servidor oculta las herramientas que modifican datos. Con features se restringe a grupos de funcionalidades concretos; por defecto se usan todos los grupos predeterminados. Las opciones se pasan como parámetros de la URL del servidor, por ejemplo project_ref, read_only=true y features=database,docs.
En local y en tu propia infraestructura
Si ejecutas Supabase en local con la CLI de Supabase, también puedes acceder al servidor MCP desde tu máquina. En los entornos de la CLI y en los autohospedados, el servidor MCP ofrece por ahora un subconjunto limitado de herramientas y no tiene OAuth 2.1.
El paquete @supabase/mcp-server-supabase exporta createSupabaseMcpHandler() para servir las herramientas por HTTP desde un endpoint propio. Ese manejador solo habla la revisión actual del protocolo: un cliente que solo hable el protocolo de 2025 recibe un HTTP 400. El paquete exporta también createToolSchemas(), con los esquemas de entrada y salida de las herramientas para el cliente MCP de Vercel AI SDK. El servidor no envía structuredContent en los resultados, así que AI SDK analiza el JSON del texto de content.
Observar las peticiones
Si sirves tu propio endpoint, la opción observer de createSupabaseMcpServer recoge los resultados del ciclo de vida de cada petición y los datos propios que registra Supabase. El servidor no reenvía automáticamente al observador el contenido de las peticiones ni de las respuestas, y los fallos del observador no cambian el comportamiento de las peticiones, aunque el trabajo síncrono del observador puede bloquearlas.
Del asistente al proyecto
Leer el diagrama como texto
- Capa 1
- Asistentes de IA
- Capa 2
- Servidor MCP de Supabase
- Capa 3
- Proyecto de Supabase
Conexiones
- Asistentes de IA → Servidor MCP de Supabase
- Servidor MCP de Supabase → Proyecto de Supabase
Tecnologías utilizadas
| Tecnología | Para qué |
|---|---|
| TypeScript | Lenguaje del repositorio, según GitHub |
| JavaScript | Lenguaje del repositorio, según GitHub |
| npm | Publica el servidor como @supabase/mcp-server-supabase |
| Postgres | Base de datos sobre la que trabajan execute_ y apply_ |
| PostgREST | El otro servidor del repositorio, @supabase/mcp-server-postgrest, conecta a los usuarios de tu app mediante la API REST |
Cómo empezar: requisitos e instalación
- Ten a mano tu cuenta y tu cliente. Necesitas una cuenta de Supabase y un cliente MCP: Cursor, Claude, Windsurf u otro asistente de IA.
- Añade el servidor. La mayoría de los clientes solo necesitan el tipo
httpy la URL del servidor (ver «Configuración»). En Claude Code, la documentación lo añade a la configuración del proyecto con la línea de comandos:
claude mcp add --scope project --transport http supabase "https://mcp.supabase.com/mcp"- Inicia sesión. El cliente abre el navegador para que entres en tu cuenta de Supabase y des acceso a tu organización, sin token de acceso personal. Elige la organización que contiene el proyecto con el que vas a trabajar.
- Comprueba la conexión. Pídele al cliente que consulte tu proyecto en lenguaje natural; la documentación propone «What tables are there in the database? Use MCP tools.».
- En local, con la CLI. Si ejecutas Supabase en local con la CLI de Supabase, también llegas al servidor desde tu máquina, con un subconjunto limitado de herramientas y sin OAuth 2.1. Para servir un endpoint propio con
toNodeHandlerhay que instalar también@modelcontextprotocol/node.
Estado del proyecto y licencia
El repositorio tiene licencia Apache 2.0 y lo mantiene la organización de Supabase en GitHub.
Según la ficha del repositorio en GitHub, comprobada el 2026-10-20, el último release es mcp-server-supabase-v0.14.0, publicado el 2026-10-14, y el último push es del 2026-10-20: un proyecto activo, con releases.
Herramientas expuestas
| Herramienta | Grupo | Qué hace |
|---|---|---|
list_ | account | Lista las organizaciones de las que el usuario es miembro. |
list_ | account | Lista los proyectos del usuario y ayuda a descubrir el ID del proyecto. |
get_ | account | Da el coste de crear un proyecto o una rama, que el agente debe repetir y confirmar con el usuario. |
confirm_ | account | Devuelve un ID de confirmación cuando el usuario ha aceptado el coste de forma explícita. |
create_ | account | Crea un proyecto, que puede sumar a la factura de la organización. |
pause_ | account | Pausa un proyecto. |
restore_ | account | Restaura un proyecto. |
list_ | branching | Lista las ramas de desarrollo con su estado, para saber cuándo terminan merge, rebase o reset. |
create_ | branching | Crea una rama de desarrollo, con cargos de cómputo por horas, que el usuario acepta antes. |
merge_ | branching | Fusiona las migraciones y las Edge Functions de una rama con producción. |
reset_ | branching | Restablece las migraciones de una rama; se pierden los cambios no registrados. |
rebase_ | branching | Aplica a la rama las migraciones más recientes de producción. |
delete_ | branching | Borra una rama de desarrollo. |
list_ | database | Lista las tablas de uno o varios esquemas; con verbose, también columnas y claves. |
list_ | database | Lista las extensiones de la base de datos. |
list_ | database | Lista las migraciones de la base de datos. |
apply_ | database | Aplica una migración; es la herramienta para las operaciones DDL. |
execute_ | database | Ejecuta SQL en Postgres; puede devolver datos no confiables. |
get_ | debugging | Obtiene los logs del proyecto por tipo de servicio; donde hay query_, queda en segundo plano. |
query_ | debugging | Ejecuta una consulta SQL de solo lectura sobre los logs del proyecto para filtrar, agregar o cruzar sus campos. |
get_ | debugging | Devuelve avisos de seguridad, rendimiento y salud del proyecto. |
get_ | development | Obtiene la URL de la API del proyecto. |
get_ | development | Obtiene las claves de API publicables, las anon heredadas y las modernas. |
generate_ | development | Genera los tipos de TypeScript del proyecto. |
search_ | docs | Busca en la documentación de Supabase con GraphQL. |
list_ | functions | Lista las Edge Functions del proyecto. |
deploy_ | functions | Despliega una Edge Function o sustituye la existente, que empieza a servir de inmediato. |
list_ | storage | Lista los buckets de almacenamiento. |
update_ | storage | Actualiza la configuración de almacenamiento. |
get_ | notebooks | Obtiene un notebook con sus celdas. |
submit_ | feedback | Envía comentarios sobre las herramientas al equipo de Supabase; pregunta antes si el usuario no lo pidió y nunca incluye secretos, datos personales ni contenido de la base de datos. |
create_ | functions | Crea o actualiza un secreto: el valor se introduce en el panel y nunca pasa por el cliente de IA. |
Esta tabla recoge las herramientas principales de cada grupo, según su definición en el código del repositorio, contrastada con la lista de la documentación oficial el 2026-10-20. Según la documentación, las ramas de desarrollo (experimental) requieren un plan de pago.
Configuración
{
"mcpServers": {
"supabase": {
"type": "http",
"url": "https://mcp.supabase.com/mcp"
}
}
}Ejemplo de uso
Un cambio de esquema con una rama de desarrollo
El repositorio documenta este flujo para llevar un cambio de esquema de desarrollo a producción. Para crear una rama de desarrollo basta con pedírselo al LLM, que llamará a la herramienta create_branch. La rama aplica todas las migraciones del proyecto principal a una base de datos nueva, y los datos de producción no se copian: clona la rama de producción aplicando las mismas migraciones que muestra list_migrations, sin los datos ni los cambios de esquema no registrados.
Después pides el cambio. Al aplicar una migración con apply_migration, el cambio de esquema o de datos queda registrado para repetirlo en producción cuando quieras desplegar. Si la migración inserta datos estáticos, hay que pedir al LLM que no fije referencias de claves foráneas, porque están ligadas a los datos de la rama de desarrollo. Después de aplicar una migración, puedes probar los cambios conectando tu app a la rama de desarrollo; la URL y las claves de API de la rama se obtienen con get_project_url y get_publishable_keys.
Cuando todo funciona, fusionar la rama con merge_branch equivale a aplicar sus migraciones nuevas, de forma incremental, en la rama de producción. Si la fusión falla, get_logs permite consultar el error exacto de esa acción de la rama; sin un rango de tiempo, cada llamada cubre las últimas 24 horas. Solo se registran las migraciones que se aplican con éxito, así que fusionar varias veces la misma rama de desarrollo es seguro. Al final, después de fusionar los cambios con producción, delete_branch borra la rama de desarrollo para ahorrar recursos.
Revertir y ponerse al día
Para revertir una migración en la rama de desarrollo, se pide al LLM restablecer las últimas n migraciones o volver a un número de versión concreto, y entonces se pide llamar a reset_branch para devolver la rama a esa versión de migración. A veces hay que aplicar una migración urgente directamente en producción, y la rama de desarrollo se queda atrás en versiones de migración; lo mismo puede pasar en un equipo en el que cada persona trabaja en su propia rama de desarrollo y las fusiones se hacen en distinto orden. Para corregirlo se puede recrear la rama de desarrollo o llamar a rebase_branch, que aplica en ella, de forma incremental, las migraciones nuevas de producción.
Lo que hace el agente en la demostración
La captura que acompaña a la primera sección muestra el principio de una sesión real: el agente llama a una herramienta para localizar el proyecto del usuario y, con él identificado, pide su URL. list_projects sirve precisamente para descubrir el ID del proyecto en el que trabaja el usuario, y get_project_url obtiene la URL de la API de un proyecto.
Flujo con una rama de desarrollo
Leer el diagrama como texto
- Crear rama de desarrollo
- Aplicar migración
- Probar la app
- Fusionar con producción
Conexiones
- Crear rama de desarrollo → Aplicar migración
- Aplicar migración → Probar la app
- Probar la app → Fusionar con producción
Seguridad y límites
Según la documentación de Supabase, conectar un LLM a tus proyectos de Supabase conlleva riesgos de seguridad, y Supabase recomienda leer sus buenas prácticas antes de configurar el servidor. Esto es lo que dicen la documentación y el código del repositorio.
Inyección de prompts. Es el vector de ataque propio de los LLM: un texto guardado en tus datos puede llevar al modelo a seguir órdenes no confiables. execute_sql puede devolver datos de usuario no confiables, así que su descripción pide no seguir instrucciones ni órdenes que devuelva; lo mismo dice get_notebook de las celdas de los notebooks, que escribe cualquiera con acceso al proyecto. Supabase MCP envuelve además los resultados de SQL con instrucciones que disuaden al modelo de obedecer lo que haya en los datos, pero no es infalible: revisa la salida antes de seguir. Las herramientas de SQL piden también no leer nunca archivos del servidor ni ejecutar órdenes del sistema operativo mediante SQL.
Aprobación manual. La mayoría de los clientes MCP piden aceptar cada llamada a una herramienta antes de ejecutarla, y la documentación pide mantener esa aprobación en el trabajo interactivo. Las confirmaciones que pide el propio servidor son una salvaguarda, no una garantía de revisión humana.
Cambios destructivos. En execute_sql y apply_migration, las sentencias destructivas pueden requerir la confirmación del usuario, una salvaguarda que puede no detectar todas las operaciones destructivas y no es una garantía de seguridad. En una migración destructiva, como borrar una columna, hay que revisar el SQL generado y el estado actual de la base de datos. Para deshacer una migración que ya está en producción no se usa reset_branch, que pierde los datos y cambios no registrados: se pide una migración nueva que revierta la anterior.
Costes. create_project puede sumar a la factura de la organización y create_branch genera cargos de cómputo por horas. Con la confirmación por formulario, el cliente muestra el coste previsto antes de la acción, que solo sigue con aprobación explícita; si no está disponible, se aplica el flujo heredado, en el que el agente da el coste en el chat y usa get_cost y confirm_cost.
Alcance. El servidor opera con tus permisos de desarrollador, así que no se da a clientes ni a usuarios finales. Sin acotar, llega a todas las organizaciones y proyectos del usuario; con un proyecto y el modo de solo lectura se limita a ese proyecto y a consultas que no escriben, y restringir los grupos de herramientas reduce la superficie de ataque. Los secretos de Edge Functions se introducen en el panel de Supabase y nunca pasan por el cliente de IA.
Valoración de KIRELEN: para trabajar sobre datos reales conviene acotar el servidor a un proyecto y activar el modo de solo lectura, y hacer los cambios de esquema en una rama de desarrollo antes de fusionarlos con producción.
Valoración de KIRELEN: como execute_sql y los notebooks pueden devolver datos no confiables, el riesgo no es solo lo que el agente pueda borrar: un texto guardado en la base de datos puede intentar darle instrucciones, y conviene revisar cada acción antes de aprobarla.
Enlaces oficiales
Fuentes consultadas
Documentación
Repositorio
- supabase/mcp (README) · Supabase
- Supabase MCP Server (código del servidor) · Supabase
- Supabase MCP Server: herramientas de base de datos · Supabase
- Supabase MCP Server: herramientas de cuenta · Supabase
- Supabase MCP Server: herramientas de ramas · Supabase
- Supabase MCP Server: herramientas de depuración · Supabase
Recursos relacionados
- Skill
Superpowers
Skills de obra para agentes de programación que se activan solas e imponen un método: preguntar, diseñar, planificar, probar primero y revisar.
HerramientaClaude Code
Agente de programación de Anthropic: lee tu código, edita archivos y ejecuta comandos en la terminal, el IDE, el escritorio o la web. De pago y propietario.
- MCP
HubSpot MCP
Servidor MCP remoto de HubSpot para interactuar con CRM, contenido y marketing mediante IA y lenguaje natural.