Supabase MCP

Serveur MCP Supabase

Connectez vos projets Supabase à Cursor, Claude, Windsurf et d'autres assistants IA.

Le Model Context Protocol (MCP) standardise la manière dont les grands modèles de langage (LLM) communiquent avec des services externes comme Supabase. Il connecte directement les assistants IA à votre projet Supabase et leur permet d'effectuer des tâches telles que la gestion des tables, la récupération de configuration et l'interrogation des données. Consultez la liste complète des outils.

Configuration

1. Suivez nos bonnes pratiques de sécurité

Avant de configurer le serveur MCP, nous vous recommandons de lire nos bonnes pratiques de sécurité pour comprendre les risques liés à la connexion d'un LLM à vos projets Supabase et comment les atténuer.

2. Configurez votre client MCP

Pour configurer le serveur MCP Supabase sur votre client, consultez notre documentation de configuration. Vous pouvez également générer une URL MCP personnalisée pour votre projet en visitant l'onglet de connexion MCP dans le tableau de bord Supabase.

Votre client MCP vous invitera automatiquement à vous connecter à Supabase lors de la configuration. Assurez-vous de choisir l'organisation qui contient le projet avec lequel vous souhaitez travailler.

La plupart des clients MCP nécessitent les informations suivantes :

{
  "mcpServers": {
    "supabase": {
      "type": "http",
      "url": "https://mcp.supabase.com/mcp"
    }
  }
}

Si vous ne voyez pas votre client MCP répertorié dans notre documentation, consultez la documentation MCP de votre client et copiez les informations MCP ci-dessus dans leur format attendu (json, yaml, etc.).

CLI

Si vous exécutez Supabase localement avec la CLI Supabase, vous pouvez accéder au serveur MCP à l'adresse http://localhost:54321/mcp. Actuellement, le serveur MCP dans les environnements CLI offre un sous-ensemble limité d'outils et pas d'OAuth 2.1.

Auto-hébergé

Pour Supabase auto-hébergé, consultez la page Activation du serveur MCP. Actuellement, le serveur MCP dans les environnements auto-hébergés offre un sous-ensemble limité d'outils et pas d'OAuth 2.1.

Options

Les options suivantes sont configurables en tant que paramètres de requête d'URL :

• read_only : Utilisé pour restreindre le serveur aux requêtes et outils en lecture seule. Recommandé par défaut. Voir mode lecture seule.
• project_ref : Utilisé pour limiter le serveur à un projet spécifique. Recommandé par défaut. Si vous omettez ceci, le serveur aura accès à tous les projets de votre compte Supabase. Voir mode limité au projet.
• features : Utilisé pour spécifier les groupes d'outils à activer. Voir groupes de fonctionnalités.

Lorsque vous utilisez l'URL dans le tableau de bord ou la documentation, ces paramètres seront renseignés pour vous.

Mode limité au projet

Sans limitation au projet, le serveur MCP aura accès à tous les projets de votre organisation Supabase. Nous vous recommandons de restreindre le serveur à un projet spécifique en définissant le paramètre de requête project_ref dans l'URL du serveur :

https://mcp.supabase.com/mcp?project_ref=<project-ref>

Remplacez <project-ref> par l'ID de votre projet. Vous pouvez le trouver sous ID du projet dans les paramètres du projet Supabase.

Après avoir limité le serveur à un projet, les outils au niveau du compte comme list_projects et list_organizations ne seront plus disponibles. Le serveur n'aura accès qu'au projet spécifié et à ses ressources.

Mode lecture seule

Pour restreindre le serveur MCP Supabase aux requêtes en lecture seule, définissez le paramètre de requête read_only dans l'URL du serveur :

https://mcp.supabase.com/mcp?read_only=true

Nous recommandons d'activer ce paramètre par défaut. Cela empêche les opérations d'écriture sur l'une de vos bases de données en exécutant SQL en tant qu'utilisateur Postgres en lecture seule (via execute_sql). Tous les autres outils de mutation sont désactivés en mode lecture seule, y compris : apply_migration create_project pause_project restore_project deploy_edge_function create_branch delete_branch merge_branch reset_branch rebase_branch update_storage_config.

Groupes de fonctionnalités

Vous pouvez activer ou désactiver des groupes d'outils spécifiques en passant le paramètre de requête features au serveur MCP. Cela vous permet de personnaliser les outils disponibles pour le LLM. Par exemple, pour activer uniquement les outils de base de données et de documentation, vous spécifieriez l'URL du serveur comme suit :

https://mcp.supabase.com/mcp?features=database,docs

Les groupes disponibles sont : account, docs, database, debugging, development, functions, storage et branching.

Si ce paramètre n'est pas défini, les groupes de fonctionnalités par défaut sont : account, database, debugging, development, docs, functions et branching.

Outils

Remarque : Ce serveur est en version pré-1.0, attendez-vous donc à des changements cassants entre les versions. Étant donné que les LLM s'adapteront automatiquement aux outils disponibles, cela ne devrait pas affecter la plupart des utilisateurs.

Les outils Supabase suivants sont disponibles pour le LLM, regroupés par fonctionnalité.

Compte

Activé par défaut lorsqu'aucun project_ref n'est défini. Utilisez account pour cibler ce groupe d'outils avec l'option features.

Remarque : ces outils ne seront pas disponibles si le serveur est limité à un projet.

• list_projects : Répertorie tous les projets Supabase pour l'utilisateur.
• get_project : Obtient les détails d'un projet.
• create_project : Crée un nouveau projet Supabase.
• pause_project : Met en pause un projet.
• restore_project : Restaure un projet.
• list_organizations : Répertorie toutes les organisations dont l'utilisateur est membre.
• get_organization : Obtient les détails d'une organisation.
• get_cost : Obtient le coût d'un nouveau projet ou d'une branche pour une organisation.
• confirm_cost : Confirme la compréhension par l'utilisateur des coûts d'un nouveau projet ou d'une branche. Ceci est requis pour créer un nouveau projet ou une branche.

Base de connaissances

Activé par défaut. Utilisez docs pour cibler ce groupe d'outils avec l'option features.

• search_docs : Recherche dans la documentation Supabase des informations à jour. Les LLM peuvent l'utiliser pour trouver des réponses à des questions ou apprendre à utiliser des fonctionnalités spécifiques.

Base de données

Activé par défaut. Utilisez database pour cibler ce groupe d'outils avec l'option features.

• list_tables : Répertorie toutes les tables dans les schémas spécifiés.
• list_extensions : Répertorie toutes les extensions de la base de données.
• list_migrations : Répertorie toutes les migrations de la base de données.
• apply_migration : Applique une migration SQL à la base de données. Le SQL passé à cet outil sera suivi dans la base de données, les LLM doivent donc l'utiliser pour les opérations DDL (changements de schéma).
• execute_sql : Exécute du SQL brut dans la base de données. Les LLM doivent l'utiliser pour les requêtes régulières qui ne modifient pas le schéma.

Débogage

Activé par défaut. Utilisez debugging pour cibler ce groupe d'outils avec l'option features.

• get_logs : Obtient les journaux d'un projet Supabase par type de service (api, postgres, edge functions, auth, storage, realtime). Les LLM peuvent l'utiliser pour aider au débogage et à la surveillance des performances des services.
• get_advisors : Obtient une liste d'avis consultatifs pour un projet Supabase. Les LLM peuvent l'utiliser pour vérifier les vulnérabilités de sécurité ou les problèmes de performance.

Développement

Activé par défaut. Utilisez development pour cibler ce groupe d'outils avec l'option features.

• get_project_url : Obtient l'URL de l'API pour un projet.
• get_publishable_keys : Obtient les clés API anonymes pour un projet. Renvoie un tableau de clés API sécurisées pour le client, y compris les anciennes clés anon et les clés publiable modernes. Les clés publiable sont recommandées pour les nouvelles applications.
• generate_typescript_types : Génère des types TypeScript basés sur le schéma de la base de données. Les LLM peuvent les enregistrer dans un fichier et les utiliser dans leur code.

Fonctions Edge

Activé par défaut. Utilisez functions pour cibler ce groupe d'outils avec l'option features.

• list_edge_functions : Répertorie toutes les fonctions Edge dans un projet Supabase.
• get_edge_function : Récupère le contenu du fichier pour une fonction Edge dans un projet Supabase.
• deploy_edge_function : Déploie une nouvelle fonction Edge sur un projet Supabase. Les LLM peuvent l'utiliser pour déployer de nouvelles fonctions ou mettre à jour des fonctions existantes.

Branchement (Expérimental, nécessite un forfait payant)

Activé par défaut. Utilisez branching pour cibler ce groupe d'outils avec l'option features.

• create_branch : Crée une branche de développement avec les migrations de la branche de production.
• list_branches : Répertorie toutes les branches de développement.
• delete_branch : Supprime une branche de développement.
• merge_branch : Fusionne les migrations et les fonctions edge d'une branche de développement vers la production.
• reset_branch : Réinitialise les migrations d'une branche de développement à une version antérieure.
• rebase_branch : Rebascule la branche de développement sur la production pour gérer la dérive de migration.

Stockage

Désactivé par défaut pour réduire le nombre d'outils. Utilisez storage pour cibler ce groupe d'outils avec l'option features.

• list_storage_buckets : Répertorie tous les buckets de stockage dans un projet Supabase.
• get_storage_config : Obtient la configuration de stockage pour un projet Supabase.
• update_storage_config : Met à jour la configuration de stockage pour un projet Supabase (nécessite un forfait payant).

Risques de sécurité

[!CONSEIL] Avant d'utiliser le serveur MCP, passez en revue les risques de sécurité et les mesures d'atténuation recommandées dans la documentation Supabase.

Utilisation avec le client MCP du SDK IA

Le package @supabase/mcp-server-supabase exporte createToolSchemas() pour remplir les schémas d'entrée et de sortie du client MCP du SDK IA de Vercel. Cela permet de traiter les outils MCP Supabase comme des outils statiques avec une validation côté client et des types TypeScript inférés pour leurs entrées et sorties.

import { createToolSchemas } from '@supabase/mcp-server-supabase';
import { createMCPClient } from '@ai-sdk/mcp';
import { streamText } from 'ai';

const mcpClient = await createMCPClient({
  transport: {
    type: 'http',
    url: 'https://mcp.supabase.com/mcp',
  },
});

const tools = await mcpClient.tools({
  schemas: createToolSchemas(),
});

const result = streamText({ model, tools, prompt: '...' });

for (const step of await result.steps) {
  for (const toolResult of step.staticToolResults) {
    if (toolResult.toolName === 'get_project_url') {
      toolResult.input;  // { project_id: string }
      toolResult.output; // { url: string }
    }
  }
}

createToolSchemas() accepte des options de filtrage similaires aux paramètres d'URL du serveur MCP :

• features : Restreindre à des groupes de fonctionnalités spécifiques (par exemple ['database', 'docs']). Par défaut, tous les groupes de fonctionnalités par défaut.
• projectScoped : Lorsque true, omet project_id des schémas d'entrée d'outil et exclut les outils au niveau du compte — à utiliser lors de la connexion à un serveur configuré avec project_ref. Par défaut false.
• readOnly : Lorsque true, exclut les outils de mutation — à utiliser lors de la connexion à un serveur configuré avec read_only=true. Par défaut false.

const mcpClient = await createMCPClient({
  transport: {
    type: 'http',
    url: 'https://mcp.supabase.com/mcp?project_ref=<project-ref>&read_only=true&features=database,docs',
  },
});

const tools = await mcpClient.tools({
  schemas: createToolSchemas({
    features: ['database', 'docs'],
    projectScoped: true,
    readOnly: true,
  }),
});

[!REMARQUE] Ce serveur n'envoie pas structuredContent dans les résultats des outils MCP. Le SDK IA se rabat sur l'analyse JSON à partir du texte content.

Pour plus d'informations, consultez Définition de schéma et Sorties d'outils typées dans la documentation du SDK IA.

Autres serveurs MCP

@supabase/mcp-server-postgrest

Le serveur MCP PostgREST vous permet de connecter vos propres utilisateurs à votre application via l'API REST. Voir plus de détails dans son README du projet.

Ressources

• Model Context Protocol : En savoir plus sur MCP et ses capacités.
• Du développement à la production : Apprenez à promouvoir en toute sécurité les changements vers les environnements de production.

Pour les développeurs

Voir CONTRIBUTING pour plus de détails sur la façon de contribuer à ce projet.

Licence

Ce projet est sous licence Apache 2.0. Voir le fichier LICENSE pour plus de détails.