Servidor MCP de Supabase

Un servidor de Protocolo de Contexto de Modelo (MCP) para interactuar con bases de datos de Supabase. Este servidor implementa el Protocolo de Contexto de Modelo mediante el SDK de Python FastMCP para proporcionar herramientas de operación de bases de datos para modelos de lenguaje grandes (LLM).

Características

• Leer registros de tablas de Supabase con filtrado, paginación y ordenación

• Crear nuevos registros (individuales o por lotes) en las tablas de Supabase

• Actualizar los registros existentes según las condiciones del filtro

• Eliminar registros de tablas según las condiciones del filtro

• Se comunica mediante el transporte Stdio de MCP

Related MCP server: Supabase MCP Server

Prerrequisitos

• Python 3.8 o superior

• Un proyecto de Supabase con tablas ya configuradas

• Clave de rol del servicio Supabase para autenticación

Instalación

1. Clonar este repositorio:

   git clone https://github.com/gevans3000/supabase-mcp.git
   cd supabase-mcp

2. Configurar un entorno virtual (recomendado):

   # Create a virtual environment
   python -m venv venv
   
   # Activate the virtual environment
   # On Windows:
   venv\Scripts\activate
   # On macOS/Linux:
   source venv/bin/activate

3. Instalar las dependencias:

   pip install -r requirements.txt

4. Configurar variables de entorno:

   • Copie el archivo .env.example a .env :

     cp .env.example .env
     # On Windows, use:
     # copy .env.example .env

   • Complete la URL de Supabase y la clave de rol de servicio en el archivo .env :

     SUPABASE_URL=your_supabase_project_url
     SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key

Uso

Iniciando el servidor

Asegúrese de que su entorno virtual esté activado, luego ejecute el servidor:

python server.py

El servidor utiliza el transporte Stdio, por lo que escuchará las solicitudes MCP en la entrada estándar y responderá en la salida estándar.

Integración con clientes MCP

Este servidor implementa el Protocolo de Contexto de Modelo y se integra con cualquier cliente compatible con MCP. Por ejemplo, puede usarlo con frameworks LLM compatibles con herramientas MCP.

Agregar a la configuración de Windsurf/Cursor MCP

Para agregar este servidor MCP a su configuración de Windsurf o Cursor:

1. Localice su archivo mcp_config.json :

   • Windows: C:\Users\<username>\.codeium\windsurf\mcp_config.json

   • macOS: ~/.codeium/windsurf/mcp_config.json

   • Linux: ~/.codeium/windsurf/mcp_config.json

2. Agregue el servidor Supabase MCP a la sección mcpServers :

{
  "mcpServers": {
    // ... other servers
    "supabase": {
      "command": "python",
      "args": [
        "/path/to/your/supabase-mcp/server.py"
      ],
      "env": {
        "SUPABASE_URL": "your_supabase_url",
        "SUPABASE_SERVICE_ROLE_KEY": "your_supabase_key"
      }
    }
  }
}

Reemplace /path/to/your/supabase-mcp/server.py con la ruta absoluta a su archivo server.py.

Nota : Para un mejor aislamiento, puede utilizar el ejecutable de Python desde su entorno virtual:

{
  "mcpServers": {
    "supabase": {
      "command": "/path/to/your/venv/bin/python",  // or "venv\\Scripts\\python.exe" on Windows
      "args": [
        "/path/to/your/supabase-mcp/server.py"
      ]
    }
  }
}

3. Reinicie su aplicación Windsurf/Cursor para aplicar los cambios.

4. Las herramientas Supabase MCP ahora estarán disponibles para su asistente de IA.

Descripciones de herramientas

El servidor proporciona las siguientes herramientas:

1. leer_registros

Lee registros de una tabla de base de datos Supabase con opciones de consulta flexibles.

Parámetros:

• table (cadena, obligatoria): nombre de la tabla desde la que se leerá

• columns (cadena, opcional, valor predeterminado: "*"): columnas para seleccionar (separadas por comas o * para todas)

• filters (objeto, opcional): condiciones de filtrado como pares clave-valor

• limit (entero, opcional): número máximo de registros a devolver

• offset (entero, opcional): Número de registros a omitir para la paginación

• order_by (objeto, opcional): Opciones de ordenamiento como pares columna:dirección

Ejemplo:

{
  "table": "users",
  "columns": "id,name,email",
  "filters": {"is_active": true},
  "limit": 10,
  "offset": 0,
  "order_by": {"created_at": "desc"}
}

2. crear_registros

Crea uno o más registros en una tabla de base de datos de Supabase.

Parámetros:

• table (cadena, obligatoria): nombre de la tabla en la que se crearán los registros

• records (objeto o matriz, obligatorio): un único objeto de registro o una matriz de objetos de registro para crear

Ejemplo (registro único):

{
  "table": "users",
  "records": {
    "name": "John Doe",
    "email": "john@example.com",
    "role": "user"
  }
}

Ejemplo (múltiples registros):

{
  "table": "users",
  "records": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "role": "user"
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "role": "admin"
    }
  ]
}

3. actualizar_registros

Actualiza registros existentes en una tabla de base de datos de Supabase según las condiciones del filtro.

Parámetros:

• table (cadena, obligatoria): nombre de la tabla en la que se actualizarán los registros

• updates (objeto, obligatorio): Campos para actualizar como pares clave-valor

• filters (objeto, obligatorio): Condiciones de filtrado para identificar registros a actualizar

Ejemplo:

{
  "table": "users",
  "updates": {
    "is_verified": true,
    "last_login_at": "2025-04-04T15:30:00Z"
  },
  "filters": {
    "id": 123
  }
}

4. eliminar_registros

Elimina registros de una tabla de base de datos de Supabase según las condiciones del filtro.

Parámetros:

• table (cadena, obligatoria): nombre de la tabla de la que se eliminarán registros

• filters (objeto, obligatorio): Condiciones de filtrado para identificar registros a eliminar

Ejemplo:

{
  "table": "expired_sessions",
  "filters": {
    "expires_at": {"lt": "2025-01-01T00:00:00Z"}
  }
}

Desarrollo

Estructura del proyecto

• server.py : Implementación del servidor MCP principal

• supabase_client.py : contenedor de cliente de Supabase

• requirements.txt : Dependencias de Python

• .env.example : archivo de variables de entorno de ejemplo

Agregar nuevas herramientas

Para agregar una nueva herramienta al servidor:

1. Defina un modelo Pydantic para los parámetros de solicitud de la herramienta en server.py

2. Agregue un método de controlador a la clase SupabaseMCPServer

3. Registre la herramienta en el método _register_tools con un nombre descriptivo y documentación

Licencia

Licencia MIT

Contribuyendo

¡Agradecemos sus contribuciones! No dude en enviar una solicitud de incorporación de cambios.