MCP + Supabase: tutorial completo

Configurar el MCP server paso a paso

Primero, necesitas un access token de Supabase. Ve a supabase.com/dashboard/account/tokens y genera uno. Este token da acceso a todos tus proyectos, así que trátalo como una credencial sensible.

Paso 1: Generar el token

1. Abre supabase.com/dashboard/account/tokens
2. Haz clic en "Generate new token"
3. Ponle un nombre descriptivo: "Claude Code MCP - desarrollo"
4. Copia el token (empieza por sbp_). No lo verás de nuevo.

Paso 2: Configurar settings.json

Añade el server a tu configuración de Claude Code. Puedes hacerlo en la configuración global (~/.claude/settings.json) o del proyecto (.claude/settings.json):

// ~/.claude/settings.json (global, todos los proyectos)
{
 "mcpServers": {
 "supabase": {
 "command": "npx",
 "args": ["-y", "@supabase/mcp-server-supabase"],
 "env": {
 "SUPABASE_ACCESS_TOKEN": "sbp_tu_token_aqui"
 }
 }
 }
}

Paso 3: Usar variable de entorno (recomendado)

Para no poner el token en un archivo que puedas subir a git por error:

# En tu ~/.zshrc o ~/.bashrc:
export SUPABASE_ACCESS_TOKEN="sbp_tu_token_aqui"

# En settings.json:
{
 "mcpServers": {
 "supabase": {
 "command": "npx",
 "args": ["-y", "@supabase/mcp-server-supabase"],
 "env": {
 "SUPABASE_ACCESS_TOKEN": "${SUPABASE_ACCESS_TOKEN}"
 }
 }
 }
}

Paso 4: Verificar conexión

Reinicia Claude Code y ejecuta /mcp para ver los servidores activos. Deberías ver "supabase" con sus herramientas listadas. Pídele "lista mis proyectos de Supabase" para confirmar que funciona.

Herramientas disponibles

El MCP server de Supabase expone estas herramientas:

• list_projects: listar todos tus proyectos de Supabase
• get_project: obtener detalles de un proyecto específico
• list_tables: ver tablas y esquema de un proyecto
• execute_sql: ejecutar cualquier query SQL
• apply_migration: aplicar migraciones de esquema
• list_migrations: ver migraciones aplicadas
• get_logs: consultar logs del proyecto
• get_advisors: obtener recomendaciones de rendimiento
• list_extensions: ver extensiones PostgreSQL disponibles
• list_edge_functions: gestionar edge functions
• deploy_edge_function: desplegar una edge function
• get_project_url: obtener URLs del proyecto (API, Auth, Storage)
• get_publishable_keys: obtener las claves anon y service_role

Operaciones CRUD con ejemplos reales

Puedes pedirle a Claude Code que ejecute queries en lenguaje natural. Veamos operaciones reales:

SELECT: Consultar datos

# Queries con lenguaje natural:
"Muéstrame los 10 usuarios más recientes"
→ SELECT * FROM auth.users ORDER BY created_at DESC LIMIT 10

"Cuántos pedidos hubo esta semana?"
→ SELECT COUNT(*) FROM orders
  WHERE created_at >= now() - interval '7 days'

"Dame las ventas agrupadas por mes del último año"
→ SELECT date_trunc('month', created_at) as mes,
  SUM(amount) as total, COUNT(*) as num_pedidos
  FROM orders
  WHERE created_at >= now() - interval '1 year'
  GROUP BY 1 ORDER BY 1

INSERT: Crear registros

# Insertar datos de prueba
"Crea 5 productos de ejemplo para la tienda"
→ INSERT INTO products (name, price, category, stock) VALUES
  ('Camiseta básica', 19.99, 'ropa', 150),
  ('Pantalón vaquero', 49.99, 'ropa', 80),
  ('Zapatillas running', 89.99, 'calzado', 45),
  ('Mochila urbana', 39.99, 'accesorios', 120),
  ('Gorra deportiva', 14.99, 'accesorios', 200);

UPDATE: Modificar registros

# Actualizar datos
"Sube un 10% el precio de todos los productos de la categoría ropa"
→ UPDATE products SET price = price * 1.10
  WHERE category = 'ropa';

"Marca como inactivos los usuarios que no se loguearon en 6 meses"
→ UPDATE profiles SET status = 'inactive'
  WHERE last_login < now() - interval '6 months';

DELETE: Eliminar registros

# Borrar datos (con precaución)
"Elimina los carritos abandonados de hace más de 30 días"
→ DELETE FROM carts
  WHERE status = 'abandoned'
  AND updated_at < now() - interval '30 days';

Claude Code traduce tu petición a SQL, la ejecuta vía MCP, y te muestra los resultados formateados. Si la query es destructiva (UPDATE, DELETE), te pide confirmación antes de ejecutarla.

Crear migraciones

Uno de los usos más potentes: crear migraciones de esquema con lenguaje natural:

# Lo que le pides:
"Añade una tabla de subscriptions con campos: id, user_id
(FK a auth.users), plan (text), status (text),
started_at, expires_at. Con RLS habilitado."

# Claude Code genera y aplica la migración:
CREATE TABLE subscriptions (
 id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
 user_id UUID REFERENCES auth.users(id) NOT NULL,
 plan TEXT NOT NULL,
 status TEXT NOT NULL DEFAULT 'active',
 started_at TIMESTAMPTZ DEFAULT now(),
 expires_at TIMESTAMPTZ
);

ALTER TABLE subscriptions ENABLE ROW LEVEL SECURITY;

CREATE POLICY "Users can view own subscriptions"
 ON subscriptions FOR SELECT
 USING (auth.uid() = user_id);

Claude Code no solo crea la tabla: aplica RLS y crea políticas de acceso porque conoce las buenas prácticas de Supabase. Otro ejemplo más complejo:

# Migración con índices, triggers y funciones
"Crea una tabla de audit_logs que registre automáticamente
cambios en la tabla orders usando un trigger"

# Claude genera:
CREATE TABLE audit_logs (
 id BIGSERIAL PRIMARY KEY,
 table_name TEXT NOT NULL,
 record_id UUID NOT NULL,
 action TEXT NOT NULL CHECK (action IN ('INSERT','UPDATE','DELETE')),
 old_data JSONB,
 new_data JSONB,
 changed_by UUID REFERENCES auth.users(id),
 changed_at TIMESTAMPTZ DEFAULT now()
);

CREATE INDEX idx_audit_logs_table ON audit_logs(table_name, record_id);
CREATE INDEX idx_audit_logs_date ON audit_logs(changed_at);

CREATE OR REPLACE FUNCTION log_order_changes()
RETURNS TRIGGER AS $$
BEGIN
 INSERT INTO audit_logs (table_name, record_id, action, old_data, new_data, changed_by)
 VALUES ('orders', COALESCE(NEW.id, OLD.id),
   TG_OP, to_jsonb(OLD), to_jsonb(NEW), auth.uid());
 RETURN COALESCE(NEW, OLD);
END;
$$ LANGUAGE plpgsql SECURITY DEFINER;

CREATE TRIGGER orders_audit
 AFTER INSERT OR UPDATE OR DELETE ON orders
 FOR EACH ROW EXECUTE FUNCTION log_order_changes();

RLS: consideraciones importantes

Row Level Security es fundamental en Supabase. Cuando usas el MCP, Claude Code ejecuta como service_role, que bypasea RLS. Esto es importante de entender:

• Queries de desarrollo/admin: se ejecutan con service_role, ven todos los datos. Perfecto para debugging y migraciones.
• Testear políticas RLS: puedes simular un usuario específico para verificar que tus políticas funcionan correctamente.

# Testear RLS simulando un usuario autenticado
"Verifica que el usuario con id X solo ve sus propios pedidos"

→ Claude ejecuta:
SET ROLE authenticated;
SET request.jwt.claims = '{"sub": "user-uuid-aqui"}';

SELECT * FROM orders;
-- Solo debería devolver los pedidos de ese usuario

RESET ROLE;  -- Volver a service_role

Buenas prácticas de RLS con MCP:

• Siempre verifica RLS después de crear una tabla: "¿Qué tablas públicas no tienen RLS habilitado?"
• Testea las políticas con SET ROLE antes de dar por buena una migración
• Crea políticas separadas para SELECT, INSERT, UPDATE y DELETE (no uses "ALL" salvo que realmente lo necesites)
• Usa auth.uid() como base para el filtrado en aplicaciones multi-tenant

Combinar con otros MCPs

El verdadero poder del MCP aparece cuando combinas varios servidores. Claude Code puede usar múltiples MCPs en una misma conversación:

Supabase + GitHub

# Flujo combinado: revisar PR que modifica esquema
"Revisa el PR #42 de mi repo. Si modifica tablas de Supabase,
verifica que las migraciones están incluidas y que RLS está configurado."

Claude:
1. Lee los archivos del PR (GitHub MCP)
2. Identifica cambios en migraciones SQL
3. Verifica el esquema actual en Supabase (Supabase MCP)
4. Compara y reporta si faltan migraciones o políticas

Supabase + filesystem

# Generar tipos TypeScript desde el esquema
"Genera los tipos TypeScript para mi proyecto basándote
en el esquema actual de Supabase"

Claude:
1. Lista tablas y columnas (Supabase MCP)
2. Genera archivo types/database.ts (filesystem)
3. Lo guarda en tu proyecto local

Supabase + Docker

# Verificar que local y remoto están sincronizados
"Compara el esquema de mi Supabase local (Docker)
con el de staging"

Claude:
1. Inspecciona la DB local via Docker MCP
2. Lee el esquema remoto via Supabase MCP
3. Muestra las diferencias

Patrones avanzados

Debugging de rendimiento

"Mi API va lenta. Revisa las queries lentas y sugiere índices." Claude usa get_advisors y execute_sql para analizar el plan de ejecución y sugerir optimizaciones.

# Análisis de rendimiento paso a paso
"Analiza el rendimiento de mi base de datos"

Claude ejecuta:
1. get_advisors → Recomendaciones de Supabase
2. SELECT * FROM pg_stat_statements ORDER BY mean_exec_time DESC LIMIT 10
   → Queries más lentas
3. EXPLAIN ANALYZE SELECT ... (para cada query lenta)
   → Plan de ejecución detallado
4. Sugiere índices específicos basados en los resultados

Auditoría de seguridad

"Verifica que todas las tablas públicas tienen RLS habilitado y políticas razonables." Claude lista tablas, revisa políticas, y reporta las que están desprotegidas.

Seed data inteligente

"Genera 50 registros de prueba para la tabla products con datos realistas que respeten las constraints y foreign keys." Claude analiza el esquema, entiende las relaciones, y genera INSERTs coherentes.

Exploración de esquema

"Explica la estructura de la base de datos y las relaciones entre tablas." Claude lee el esquema completo y genera una explicación legible con un diagrama de relaciones.

Troubleshooting

Problemas comunes y sus soluciones:

El MCP no aparece en /mcp

• Verifica que tienes Node.js instalado (npx lo necesita)
• Comprueba que el JSON en settings.json es válido (sin comas extra)
• Reinicia Claude Code completamente (no solo la conversación)
• Ejecuta npx -y @supabase/mcp-server-supabase manualmente para ver si hay errores de instalación

Error de autenticación

• Verifica que el token es válido en supabase.com/dashboard/account/tokens
• Si usas variable de entorno, asegúrate de que está exportada en el shell donde arrancas Claude Code
• Tokens antiguos pueden expirar. Genera uno nuevo si han pasado meses.

Timeout en queries largas

• Las queries pesadas pueden superar el timeout del MCP. Divide en queries más pequeñas.
• Para migraciones grandes (ALTER TABLE en tablas con millones de filas), hazlas directamente desde el dashboard.
• Usa EXPLAIN antes de ejecutar para estimar el tiempo.

El MCP no ve mi proyecto nuevo

• Los proyectos recién creados pueden tardar unos segundos en aparecer via API.
• Pide "lista mis proyectos" para verificar que el proyecto está visible.
• Verifica que el token tiene acceso a la organización donde está el proyecto.

Seguridad

• Tokens de desarrollo: usa un token con acceso a tu proyecto de staging, no de producción
• No guardes tokens en git: usa variables de entorno del sistema o un gestor de secretos
• Revisa antes de aplicar: Claude Code te muestra la migración antes de aplicarla. Lee el SQL
• Backups: antes de migraciones destructivas, asegúrate de tener un backup reciente
• Producción: usa --allowedTools para limitar a operaciones de lectura en entornos de producción

Preguntas frecuentes

¿Puedo usar MCP Supabase con el plan gratuito?

Sí. El MCP funciona con cualquier plan de Supabase. El token de acceso es independiente del plan del proyecto. Las únicas limitaciones son las del propio plan (tamaño de DB, bandwidth, etc.).

¿Puedo conectar múltiples proyectos Supabase?

Sí. Un solo token da acceso a todos los proyectos de tu cuenta. Cuando pides algo, Claude Code te pregunta a qué proyecto te refieres si tienes varios. También puedes especificar directamente: "En el proyecto staging, lista las tablas."

¿Las queries se quedan en algún log?

Las queries ejecutadas via MCP aparecen en los logs normales de Supabase (pg_stat_statements, logs del dashboard). Son indistinguibles de queries ejecutadas desde cualquier otro cliente. No hay un log específico de MCP.

¿Es posible ejecutar migraciones de Prisma o Drizzle via MCP?

No directamente. El MCP de Supabase usa su propio formato de migraciones (SQL puro). Pero puedes pedirle a Claude que lea tus migraciones de Prisma/Drizzle y las traduzca a SQL para aplicarlas via MCP.

Siguiente paso

Conecta Supabase a Claude Code y empieza con queries simples. Cuando te sientas cómodo, pasa a migraciones y gestión de esquema. La curva de aprendizaje es mínima porque interactúas en lenguaje natural.

Explora también MCP + GitHub y la guía general de configuración de MCP servers. Si quieres entender los fundamentos de la configuración de Claude Code, lee settings.json: configuración avanzada.