Self-Hosted Supabase MCP Server

Selbstgehosteter Supabase MCP-Server

Überblick

Dieses Projekt bietet einen Model Context Protocol (MCP) -Server, der speziell für die Interaktion mit selbstgehosteten Supabase-Instanzen entwickelt wurde. Es schließt die Lücke zwischen MCP-Clients (wie IDE-Erweiterungen) und Ihren lokalen oder privat gehosteten Supabase-Projekten und ermöglicht Datenbankanalyse, -verwaltung und -interaktion direkt aus Ihrer Entwicklungsumgebung.

Dieser Server wurde von Grund auf neu erstellt, wobei die Erkenntnisse aus der Anpassung des offiziellen Supabase-Cloud-MCP-Servers genutzt wurden, um eine minimale, fokussierte Implementierung bereitzustellen, die auf den selbst gehosteten Anwendungsfall zugeschnitten ist.

Zweck

Das Hauptziel dieses Servers besteht darin, Entwicklern, die selbst gehostete Supabase-Installationen verwenden, die Nutzung MCP-basierter Tools für Aufgaben wie die folgenden zu ermöglichen:

• Abfragen von Datenbankschemata und Daten.
• Verwalten von Datenbankmigrationen.
• Überprüfen von Datenbankstatistiken und -verbindungen.
• Verwalten von Authentifizierungsbenutzern.
• Interaktion mit Supabase Storage.
• Generieren von Typdefinitionen.

Es vermeidet die Komplexität des offiziellen Cloud-Servers im Zusammenhang mit Multiprojektmanagement und Cloud-spezifischen APIs und bietet eine optimierte Erfahrung für Einzelprojekt- und selbstgehostete Umgebungen.

Funktionen (Implementierte Tools)

Der Server stellt MCP-Clients die folgenden Tools zur Verfügung:

• Schema und Migrationen
  • list_tables : Listet Tabellen in den Datenbankschemata auf.
  • list_extensions : Listet installierte PostgreSQL-Erweiterungen auf.
  • list_migrations : Listet angewendete Supabase-Migrationen auf.
  • apply_migration : Wendet ein SQL-Migrationsskript an.
• Datenbankoperationen und Statistiken
  • execute_sql : Führt eine beliebige SQL-Abfrage aus (über RPC oder direkte Verbindung).
  • get_database_connections : Zeigt aktive Datenbankverbindungen ( pg_stat_activity ).
  • get_database_stats : Ruft Datenbankstatistiken ab ( pg_stat_* ).
• Projektkonfiguration und Schlüssel
  • get_project_url : Gibt die konfigurierte Supabase-URL zurück.
  • get_anon_key : Gibt den konfigurierten Supabase-Anon-Schlüssel zurück.
  • get_service_key : Gibt den konfigurierten Supabase-Servicerollenschlüssel zurück (sofern angegeben).
  • verify_jwt_secret : Überprüft, ob das JWT-Geheimnis konfiguriert ist, und gibt eine Vorschau zurück.
• Entwicklungs- und Erweiterungstools
  • generate_typescript_types : Generiert TypeScript-Typen aus dem Datenbankschema.
  • rebuild_hooks : Versucht, den pg_net Worker neu zu starten (falls verwendet).
• Auth-Benutzerverwaltung
  • list_auth_users : Listet Benutzer von auth.users auf.
  • get_auth_user : Ruft Details für einen bestimmten Benutzer ab.
  • create_auth_user : Erstellt einen neuen Benutzer (erfordert direkten Datenbankzugriff, unsichere Kennwortverwaltung).
  • delete_auth_user : Löscht einen Benutzer (erfordert direkten Datenbankzugriff).
  • update_auth_user : Aktualisiert Benutzerdetails (erfordert direkten Datenbankzugriff, unsichere Kennwortverwaltung).
• Speichereinblicke
  • list_storage_buckets : Listet alle Speicher-Buckets auf.
  • list_storage_objects : Listet Objekte innerhalb eines bestimmten Buckets auf.
• Echtzeitinspektion
  • list_realtime_publications : Listet PostgreSQL-Veröffentlichungen auf (oft supabase_realtime ).

(Hinweis: get_logs war ursprünglich geplant, wurde aber aufgrund der Implementierungskomplexität in einer selbst gehosteten Umgebung übersprungen).

Setup und Installation

Installation über Smithery

So installieren Sie den selbstgehosteten Supabase MCP-Server für Claude Desktop automatisch über Smithery :

Voraussetzungen

• Node.js (Version 18.x oder höher empfohlen)
• npm (normalerweise in Node.js enthalten)
• Zugriff auf Ihre selbst gehostete Supabase-Instanz (URL, Schlüssel, möglicherweise direkte DB-Verbindungszeichenfolge).

Schritte

1. Klonen Sie das Repository:
   git clone <repository-url> cd self-hosted-supabase-mcp
2. Installieren Sie Abhängigkeiten:
   npm install
3. Erstellen Sie das Projekt:
   npm run build
   Dadurch wird der TypeScript-Code im Verzeichnis dist in JavaScript kompiliert.

Konfiguration

Der Server benötigt Konfigurationsdetails für Ihre Supabase-Instanz. Diese können über Kommandozeilenargumente oder Umgebungsvariablen bereitgestellt werden. CLI-Argumente haben Vorrang.

Erforderlich:

• --url <url> oder SUPABASE_URL=<url> : Die Haupt-HTTP-URL Ihres Supabase-Projekts (z. http://localhost:8000 ).
• --anon-key <key> oder SUPABASE_ANON_KEY=<key> : Der anonyme Schlüssel Ihres Supabase-Projekts.

Optional (aber für bestimmte Tools empfohlen/erforderlich):

• --service-key <key> oder SUPABASE_SERVICE_ROLE_KEY=<key> : Der Servicerollenschlüssel Ihres Supabase-Projekts. Wird für Vorgänge benötigt, die erhöhte Berechtigungen erfordern, z. B. der Versuch, die Hilfsfunktion execute_sql automatisch zu erstellen, falls sie nicht vorhanden ist.
• --db-url <url> oder DATABASE_URL=<url> : Die direkte PostgreSQL-Verbindungszeichenfolge für Ihre Supabase-Datenbank (z. B. postgresql://postgres:password@localhost:5432/postgres ). Erforderlich für Tools, die direkten Datenbankzugriff oder Transaktionen benötigen ( apply_migration , Authentifizierungstools, Speichertools, Abfragen von pg_catalog usw.).
• --jwt-secret <secret> oder SUPABASE_AUTH_JWT_SECRET=<secret> : Das JWT-Geheimnis Ihres Supabase-Projekts. Wird für Tools wie verify_jwt_secret benötigt.
• --tools-config <path> : Pfad zu einer JSON-Datei, die angibt, welche Tools aktiviert werden sollen (Whitelist). Wird dieser Pfad weggelassen, werden alle im Server definierten Tools aktiviert. Die Datei sollte das Format {"enabledTools": ["tool_name_1", "tool_name_2"]} haben.

Wichtige Hinweise:

• execute_sql -Hilfsfunktion: Viele Tools benötigen die Funktion public.execute_sql in Ihrer Supabase-Datenbank für eine sichere und effiziente SQL-Ausführung über RPC. Der Server sucht beim Start nach dieser Funktion. Fehlt sie und sind ein service-key (oder SUPABASE_SERVICE_ROLE_KEY ) und db-url (oder DATABASE_URL ) angegeben, wird versucht, die Funktion zu erstellen und die erforderlichen Berechtigungen zu erteilen. Schlägt die Erstellung fehl oder fehlen Schlüssel, können Tools, die ausschließlich auf RPC basieren, fehlschlagen.
• Direkter Datenbankzugriff: Tools, die direkt mit privilegierten Schemata ( auth , storage ) oder Systemkatalogen ( pg_catalog ) interagieren, erfordern im Allgemeinen, dass die DATABASE_URL für eine direkte pg Verbindung konfiguriert wird.

Verwendung

Führen Sie den Server mit Node.js aus und stellen Sie die erforderliche Konfiguration bereit:

Der Server kommuniziert über Standard-Ein-/Ausgabe (stdio) und kann von einer MCP-Client-Anwendung (z. B. einer IDE-Erweiterung wie Cursor) aufgerufen werden. Der Client verbindet sich mit dem stdio-Stream des Servers, um die verfügbaren Tools aufzulisten und aufzurufen.

Beispiele für Clientkonfigurationen

Nachfolgend finden Sie Beispiele zur Konfiguration beliebter MCP-Clients für die Verwendung dieses selbstgehosteten Servers.

Wichtig:

• Ersetzen Sie Platzhalter wie <your-supabase-url> , <your-anon-key> >, < <your-db-url> , <path-to-dist/index.js> usw. durch Ihre tatsächlichen Werte.
• Stellen Sie sicher, dass der Pfad zur kompilierten Serverdatei ( dist/index.js ) für Ihr System korrekt ist.
• Seien Sie vorsichtig, wenn Sie vertrauliche Schlüssel direkt in Konfigurationsdateien speichern, insbesondere wenn diese der Versionskontrolle unterliegen. Erwägen Sie die Verwendung von Umgebungsvariablen oder sichereren Methoden, sofern diese vom Client unterstützt werden.

Cursor

1. Erstellen oder öffnen Sie die Datei .cursor/mcp.json in Ihrem Projektstamm.
2. Fügen Sie die folgende Konfiguration hinzu:
   { "mcpServers": { "selfhosted-supabase": { "command": "node", "args": [ "<path-to-dist/index.js>", // e.g., "F:/Projects/mcp-servers/self-hosted-supabase-mcp/dist/index.js" "--url", "<your-supabase-url>", // e.g., "http://localhost:8000" "--anon-key", "<your-anon-key>", // Optional - Add these if needed by the tools you use "--service-key", "<your-service-key>", "--db-url", "<your-db-url>", // e.g., "postgresql://postgres:password@host:port/postgres" "--jwt-secret", "<your-jwt-secret>", // Optional - Whitelist specific tools "--tools-config", "<path-to-your-mcp-tools.json>" // e.g., "./mcp-tools.json" ] } } }

Visual Studio Code (Copilot)

VS Code Copilot ermöglicht die Verwendung von Umgebungsvariablen, die über Eingabeaufforderungen gefüllt werden, was für Schlüssel sicherer ist.

1. Erstellen oder öffnen Sie die Datei .vscode/mcp.json in Ihrem Projektstamm.
2. Fügen Sie die folgende Konfiguration hinzu:
   { "inputs": [ { "type": "promptString", "id": "sh-supabase-url", "description": "Self-Hosted Supabase URL", "default": "http://localhost:8000" }, { "type": "promptString", "id": "sh-supabase-anon-key", "description": "Self-Hosted Supabase Anon Key", "password": true }, { "type": "promptString", "id": "sh-supabase-service-key", "description": "Self-Hosted Supabase Service Key (Optional)", "password": true, "required": false }, { "type": "promptString", "id": "sh-supabase-db-url", "description": "Self-Hosted Supabase DB URL (Optional)", "password": true, "required": false }, { "type": "promptString", "id": "sh-supabase-jwt-secret", "description": "Self-Hosted Supabase JWT Secret (Optional)", "password": true, "required": false }, { "type": "promptString", "id": "sh-supabase-server-path", "description": "Path to self-hosted-supabase-mcp/dist/index.js" }, { "type": "promptString", "id": "sh-supabase-tools-config", "description": "Path to tools config JSON (Optional, e.g., ./mcp-tools.json)", "required": false } ], "servers": { "selfhosted-supabase": { "command": "node", // Arguments are passed via environment variables set below OR direct args for non-env options "args": [ "${input:sh-supabase-server-path}", // Use direct args for options not easily map-able to standard env vars like tools-config // Check if tools-config input is provided before adding the argument ["--tools-config", "${input:sh-supabase-tools-config}"] // Alternatively, pass all as args if simpler: // "--url", "${input:sh-supabase-url}", // "--anon-key", "${input:sh-supabase-anon-key}", // ... etc ... ], "env": { "SUPABASE_URL": "${input:sh-supabase-url}", "SUPABASE_ANON_KEY": "${input:sh-supabase-anon-key}", "SUPABASE_SERVICE_ROLE_KEY": "${input:sh-supabase-service-key}", "DATABASE_URL": "${input:sh-supabase-db-url}", "SUPABASE_AUTH_JWT_SECRET": "${input:sh-supabase-jwt-secret}" // The server reads these environment variables as fallbacks if CLI args are missing } } } }
3. Wenn Sie Copilot Chat im Agentenmodus (@workspace) verwenden, sollte der Server erkannt werden. Beim ersten Aufruf des Servers werden Sie aufgefordert, die Details (URL, Schlüssel, Pfad) einzugeben.

Andere Kunden (Windsurf, Cline, Claude)

Passen Sie die für Cursor oder die offizielle Supabase-Dokumentation angezeigte Konfigurationsstruktur an und ersetzen Sie den command und args durch den node und die Argumente für diesen Server, ähnlich dem Cursor-Beispiel:

Informationen zum Platzieren der mcp.json oder entsprechenden Konfigurationsdatei finden Sie in der spezifischen Dokumentation für jeden Client.

Entwicklung

• Sprache: TypeScript
• Build: tsc (TypeScript-Compiler)
• Abhängigkeiten: Verwaltet über npm ( package.json )
• Kernbibliotheken: @supabase/supabase-js , pg (Node-Postgres), zod (Validierung), commander (CLI-Argumente), @modelcontextprotocol/sdk (MCP-Server-Framework).

Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert. Weitere Informationen finden Sie in der Datei LICENSE.