supabase-mcp-installation-guide

Esta guía te ayudará a instalar y configurar Supabase MCP Server paso a paso.

Tabla de Contenidos

1. Prerrequisitos
2. Instalación
3. Configuración
4. Integración con Cursor
5. Verificación
6. Solución de Problemas

Prerrequisitos

Antes de comenzar, asegúrate de tener:

1. Python 3.12 o superior instalado en tu sistema
   • Puedes verificar tu versión de Python con: python --version
2. Un cliente MCP compatible:
   • Cursor (recomendado)
   • Windsurf
   • Cline
   • Claude Desktop

Instalación

Método 1: Usando pipx (Recomendado)

pipx install supabase-mcp-server

Método 2: Usando uv

uv pip install supabase-mcp-server

Configuración

Variables de Entorno Necesarias

Requeridas:

• SUPABASE_PROJECT_REF: Tu ID de proyecto Supabase
• SUPABASE_DB_PASSWORD: Tu contraseña de base de datos
• SUPABASE_REGION: Región AWS donde está alojado tu proyecto

Opcionales:

• SUPABASE_ACCESS_TOKEN: Token de acceso personal para la API de gestión
• SUPABASE_SERVICE_ROLE_KEY: Clave de rol de servicio para SDK de Auth Admin

Configuración Global en Windows

1. Crear el directorio de configuración:

mkdir -Force "$env:APPDATA\supabase-mcp"

2. Crear y editar el archivo .env:

notepad "$env:APPDATA\supabase-mcp\.env"

3. Añadir la siguiente configuración:

SUPABASE_PROJECT_REF=tu-proyecto-ref
SUPABASE_DB_PASSWORD=tu-contraseña-db
SUPABASE_REGION=us-east-1
SUPABASE_ACCESS_TOKEN=tu-token-acceso
SUPABASE_SERVICE_ROLE_KEY=tu-clave-rol-servicio

Dónde Encontrar la Información de tu Proyecto Supabase

1. Project Reference:

   • Ve a tu URL de proyecto Supabase: https://supabase.com/dashboard/project/<project-ref>
   • El project-ref es el identificador en la URL

2. Database Password:

   • Se configura durante la creación del proyecto
   • O se puede encontrar en Project Settings → Database

3. Access Token:

   • Generar en https://supabase.com/dashboard/account/tokens

4. Service Role Key:

   • Se encuentra en Project Settings → API → Project API keys

Integración con Cursor

1. Abre Cursor
2. Ve a Settings → Features → MCP Servers
3. Añade un nuevo servidor con esta configuración:

name: supabase
type: command
command: C:\Users\<usuario>\.local\bin\supabase-mcp-server.exe

Para encontrar la ruta exacta del ejecutable:

where.exe supabase-mcp-server

Verificación

Paso 1: Verificar la Instalación

Abre una terminal y ejecuta:

supabase-mcp-server

Si no hay errores, el servidor está instalado correctamente.

Paso 2: Verificar en Cursor

• Deberías ver un punto verde junto al servidor
• El número de herramientas disponibles debería ser visible

Solución de Problemas

Error: "No tools found"

1. Usa la ruta completa al ejecutable en la configuración de Cursor
2. Verifica las variables de entorno

Acceso a los Logs

En Windows, ver los logs:

Get-Content "$env:USERPROFILE\.local\share\supabase-mcp\mcp_server.log"

Problemas Comunes de Conexión

1. Verifica que el SUPABASE_PROJECT_REF sea correcto
2. Asegúrate que la región (SUPABASE_REGION) coincida con tu proyecto
3. Confirma que la contraseña de la base de datos sea correcta

Regiones Soportadas

• us-west-1: Oeste de EE.UU. (California del Norte)
• us-east-1: Este de EE.UU. (Virginia del Norte) - por defecto
• us-east-2: Este de EE.UU. (Ohio)
• ca-central-1: Canadá (Central)
• eu-west-1: Oeste de UE (Irlanda)
• eu-west-2: Europa Occidental (Londres)
• eu-central-1: UE Central (Frankfurt)
• Y más...

Recursos Adicionales

• Repositorio oficial de Supabase MCP Server
• Documentación de Supabase
• Comunidad de Supabase

Soporte

Si encuentras problemas durante la instalación:

1. Revisa los logs del servidor
2. Verifica que todas las variables de entorno estén correctamente configuradas
3. Asegúrate de tener los permisos necesarios en tu sistema
4. Consulta la sección de issues en GitHub