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

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

Clonar este repositorio:
git clone https://github.com/gevans3000/supabase-mcp.git cd supabase-mcp
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
Instalar las dependencias:
pip install -r requirements.txt
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:

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
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"
      ]
    }
  }
}

Reinicie su aplicación Windsurf/Cursor para aplicar los cambios.
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:

Defina un modelo Pydantic para los parámetros de solicitud de la herramienta en server.py
Agregue un método de controlador a la clase SupabaseMCPServer
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.