Servidor MCP de Supabase

Un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona herramientas integrales para interactuar con bases de datos, almacenamiento y funciones perimetrales de Supabase. Este servidor permite una integración fluida entre los servicios de Supabase y las aplicaciones compatibles con MCP.

Descripción general

El servidor Supabase MCP actúa como un puente entre los clientes MCP y el conjunto de servicios de Supabase, proporcionando:

Operaciones de bases de datos con amplias capacidades de consulta
Gestión de almacenamiento para archivos y activos
Invocación de función de borde
Gestión de proyectos y organizaciones
Autenticación y gestión de usuarios
Control de acceso basado en roles

Arquitectura

El servidor está construido con TypeScript y sigue una arquitectura modular:

supabase-server/
├── src/
│   ├── index.ts              # Main server implementation
│   └── types/
│       └── supabase.d.ts     # Type definitions
├── package.json
├── tsconfig.json
├── config.json.example       # Example configuration file
└── .env.example             # Environment variables template

Componentes clave

Clase de servidor : implementa la interfaz del servidor MCP y maneja todas las solicitudes del cliente
Definiciones de tipo : definiciones completas de TypeScript para todas las operaciones
Configuración del entorno : gestión segura de la configuración mediante variables de entorno
Manejo de errores : Manejo de errores robusto con mensajes de error detallados

Prerrequisitos

Node.js 16.x o superior
Un proyecto de Supabase con:
- URL del proyecto
- Clave de rol de servicio (para operaciones administrativas)
- Token de acceso (para operaciones de gestión)
Cliente compatible con MCP

Instalación

Instalación mediante herrería

Para instalar Supabase Server para Claude Desktop automáticamente a través de Smithery :

npx -y @smithery/cli install supabase-server --client claude

Clonar el repositorio:

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

Instalar dependencias:

npm install

Crear configuración de entorno:

cp .env.example .env

Configurar variables de entorno:

SUPABASE_URL=your_project_url_here
SUPABASE_KEY=your_service_role_key_here
SUPABASE_ACCESS_TOKEN=your_access_token_here  # Required for management operations

Crear configuración del servidor:

cp config.json.example config.json

Construir el servidor:

npm run build

Configuración

El servidor admite una configuración exhaustiva mediante variables de entorno y un archivo config.json. A continuación, se detallan las opciones de configuración:

Configuración del servidor

{
  "server": {
    "name": "supabase-server",    // Server name
    "version": "0.1.0",           // Server version
    "port": 3000,                 // Port number (if running standalone)
    "host": "localhost"           // Host address (if running standalone)
  }
}

Configuración de Supabase

{
  "supabase": {
    "project": {
      "url": "your_project_url",
      "key": "your_service_role_key",
      "accessToken": "your_access_token"
    },
    "storage": {
      "defaultBucket": "public",           // Default storage bucket
      "maxFileSize": 52428800,            // Max file size in bytes (50MB)
      "allowedMimeTypes": [               // Allowed file types
        "image/*",
        "application/pdf",
        "text/*"
      ]
    },
    "database": {
      "maxConnections": 10,               // Max DB connections
      "timeout": 30000,                   // Query timeout in ms
      "ssl": true                         // SSL connection
    },
    "auth": {
      "autoConfirmUsers": false,          // Auto-confirm new users
      "disableSignup": false,             // Disable public signups
      "jwt": {
        "expiresIn": "1h",               // Token expiration
        "algorithm": "HS256"              // JWT algorithm
      }
    }
  }
}

Configuración de registro

{
  "logging": {
    "level": "info",                      // Log level
    "format": "json",                     // Log format
    "outputs": ["console", "file"],       // Output destinations
    "file": {
      "path": "logs/server.log",          // Log file path
      "maxSize": "10m",                   // Max file size
      "maxFiles": 5                       // Max number of files
    }
  }
}

Configuración de seguridad

{
  "security": {
    "cors": {
      "enabled": true,
      "origins": ["*"],
      "methods": ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
      "allowedHeaders": ["Content-Type", "Authorization"]
    },
    "rateLimit": {
      "enabled": true,
      "windowMs": 900000,                 // 15 minutes
      "max": 100                          // Max requests per window
    }
  }
}

Configuración de monitorización

{
  "monitoring": {
    "enabled": true,
    "metrics": {
      "collect": true,
      "interval": 60000                   // Collection interval in ms
    },
    "health": {
      "enabled": true,
      "path": "/health"                   // Health check endpoint
    }
  }
}

Consulte config.json.example para obtener un archivo de configuración de ejemplo completo.

Integración MCP

Agregue el servidor a su configuración de MCP (cline_mcp_settings.json):

{
  "mcpServers": {
    "supabase": {
      "command": "node",
      "args": ["path/to/supabase-server/build/index.js"],
      "env": {
        "SUPABASE_URL": "your_project_url",
        "SUPABASE_KEY": "your_service_role_key",
        "SUPABASE_ACCESS_TOKEN": "your_access_token"
      },
      "config": "path/to/config.json"  // Optional: path to configuration file
    }
  }
}

Herramientas disponibles

Operaciones de base de datos

crear_registro

Cree un nuevo registro en una tabla con soporte para devolver campos específicos.

{
  table: string;
  data: Record<string, any>;
  returning?: string[];
}

Ejemplo:

{
  table: "users",
  data: {
    name: "John Doe",
    email: "john@example.com"
  },
  returning: ["id", "created_at"]
}

leer_registros

Leer registros con filtrado avanzado, uniones y selección de campos.

{
  table: string;
  select?: string[];
  filter?: Record<string, any>;
  joins?: Array<{
    type?: 'inner' | 'left' | 'right' | 'full';
    table: string;
    on: string;
  }>;
}

Ejemplo:

{
  table: "posts",
  select: ["id", "title", "user.name"],
  filter: { published: true },
  joins: [{
    type: "left",
    table: "users",
    on: "posts.user_id=users.id"
  }]
}

actualizar_registro

Actualice registros con capacidades de filtrado y devolución.

{
  table: string;
  data: Record<string, any>;
  filter?: Record<string, any>;
  returning?: string[];
}

Ejemplo:

{
  table: "users",
  data: { status: "active" },
  filter: { email: "john@example.com" },
  returning: ["id", "status", "updated_at"]
}

eliminar_registro

Eliminar registros con capacidades de filtrado y devolución.

{
  table: string;
  filter?: Record<string, any>;
  returning?: string[];
}

Ejemplo:

{
  table: "posts",
  filter: { status: "draft" },
  returning: ["id", "title"]
}

Operaciones de almacenamiento

subir_archivo

Sube archivos a Supabase Storage con opciones configurables.

{
  bucket: string;
  path: string;
  file: File | Blob;
  options?: {
    cacheControl?: string;
    contentType?: string;
    upsert?: boolean;
  };
}

Ejemplo:

{
  bucket: "avatars",
  path: "users/123/profile.jpg",
  file: imageBlob,
  options: {
    contentType: "image/jpeg",
    upsert: true
  }
}

archivo de descarga

Descargar archivos de Supabase Storage.

{
  bucket: string;
  path: string;
}

Ejemplo:

{
  bucket: "documents",
  path: "reports/annual-2023.pdf"
}

Funciones de borde

función_invocar

Invocar funciones de Supabase Edge con parámetros y opciones personalizadas.

{
  function: string;
  params?: Record<string, any>;
  options?: {
    headers?: Record<string, string>;
    responseType?: 'json' | 'text' | 'arraybuffer';
  };
}

Ejemplo:

{
  function: "process-image",
  params: {
    url: "https://example.com/image.jpg",
    width: 800
  },
  options: {
    responseType: "json"
  }
}

Gestión de usuarios

lista_usuarios

Enumere usuarios con soporte de paginación.

{
  page?: number;
  per_page?: number;
}

crear_usuario

Crear un nuevo usuario con metadatos.

{
  email: string;
  password: string;
  data?: Record<string, any>;
}

actualizar_usuario

Actualizar los detalles del usuario.

{
  user_id: string;
  email?: string;
  password?: string;
  data?: Record<string, any>;
}

eliminar_usuario

Eliminar un usuario.

{
  user_id: string;
}

asignar_rol_de_usuario

Asignar un rol a un usuario.

{
  user_id: string;
  role: string;
}

eliminar_rol_de_usuario

Eliminar un rol de un usuario.

{
  user_id: string;
  role: string;
}

Manejo de errores

El servidor proporciona mensajes de error detallados para escenarios comunes:

Parámetros no válidos
Errores de autenticación
Problemas de permisos
Limitación de velocidad
Errores de red
Restricciones de la base de datos

Los errores se devuelven en un formato estandarizado:

{
  code: ErrorCode;
  message: string;
  details?: any;
}

Desarrollo

Ejecución de pruebas

npm test

Edificio

npm run build

Pelusa

npm run lint

Contribuyendo

Bifurcar el repositorio
Crear una rama de características
Confirme sus cambios
Empujar hacia la rama
Crear una solicitud de extracción

Licencia

Licencia MIT: consulte LICENCIA para obtener más detalles

Apoyo

Para obtener ayuda, por favor:

Verifique los problemas para detectar problemas/soluciones existentes
Crear un nuevo problema con pasos de reproducción detallados
Incluya mensajes de error relevantes y detalles del entorno

Integrations

Servidor MCP de Supabase

Descripción general

Arquitectura

Componentes clave

Prerrequisitos

Instalación

Instalación mediante herrería

Configuración

Configuración del servidor

Configuración de Supabase

Configuración de registro

Configuración de seguridad

Configuración de monitorización

Integración MCP

Herramientas disponibles

Operaciones de base de datos

crear_registro

leer_registros

actualizar_registro

eliminar_registro

Operaciones de almacenamiento

subir_archivo

archivo de descarga

Funciones de borde

función_invocar

Gestión de usuarios

lista_usuarios

crear_usuario

actualizar_usuario

eliminar_usuario

asignar_rol_de_usuario

eliminar_rol_de_usuario

Manejo de errores

Desarrollo

Ejecución de pruebas

Edificio

Pelusa

Contribuyendo

Licencia

Apoyo

Tools

Appeared in Searches