managarten/apps-archived/maerchenzauber/docs/MCP_SERVER_SETUP.md

MCP Server Setup für Märchenzauber

Übersicht

Dieses Dokument beschreibt die Einrichtung eines Model Context Protocol (MCP) Servers für die Supabase-Datenbank von Märchenzauber. Mit MCP kann Claude Code direkt mit der Supabase-Datenbank interagieren, Queries ausführen, Tabellen analysieren und Migrationen durchführen.

Was ist MCP?

Model Context Protocol (MCP) ist ein Standard, der es Large Language Models (LLMs) wie Claude ermöglicht, mit externen Tools, Datenbanken und APIs zu kommunizieren. MCP erweitert die Fähigkeiten von Claude Code durch:

• Direkte Datenbankabfragen
• Tabellenverwaltung und -analyse
• Automatisierte Migrationen
• Zugriff auf Konfigurationen
• Natürlichsprachige Datenbankinteraktionen

Supabase MCP Server Features

Der offizielle Supabase MCP Server bietet über 20 Tools in verschiedenen Kategorien:

Verfügbare Tool-Gruppen

• Account: Account-Management
• Knowledge Base: Dokumentation und Wissen
• Database: Tabellen, Queries, Schema-Management
• Debugging: Logs und Fehleranalyse
• Development: Entwicklungstools
• Edge Functions: Serverless Functions
• Branching: Database Branching
• Storage: Dateiverwaltung

Hauptfunktionen

• execute_sql: SQL-Queries ausführen (SELECT, INSERT, UPDATE, DELETE)
• apply_migration: Schema-Änderungen und Migrationen anwenden
• Tabellenanalyse und -erstellung
• Automatische DDL-Generierung

Setup-Anleitung

Voraussetzungen

1. Claude Code installiert und eingerichtet
2. Supabase Account mit aktivem Projekt
3. Supabase Projekt-Referenz (projekt_ref aus der Supabase URL)

Schritt 1: Sicherheitsüberlegungen

WICHTIG: Bevor du MCP einrichtest, beachte folgende Sicherheitshinweise:

⚠️ Sicherheitswarnungen

• Niemals mit Produktion verbinden: Nutze MCP nur für Development-Projekte
• Prompt Injection: AI-Assistenten können durch manipulierte Eingaben zu ungewollten Queries verleitet werden
• Developer-Permissions: Der MCP Server arbeitet mit deinen Entwickler-Rechten
• Kein End-User-Tool: MCP ist nur für interne Entwicklung gedacht

✅ Best Practices

1. Read-Only Mode: Nutze den Read-Only Modus für maximale Sicherheit
2. Projekt-Scoping: Beschränke den Server auf ein spezifisches Projekt
3. Database Branching: Nutze Supabase Branches für sichere Tests
4. Manual Approval: Aktiviere manuelle Bestätigung für Tool-Aufrufe
5. Feature-Einschränkung: Aktiviere nur benötigte Tool-Gruppen

Schritt 2: MCP Server konfigurieren

Der Supabase MCP Server ist als Remote HTTP Server verfügbar und benötigt keine lokale Installation.

Option A: Mit Claude Code CLI (Empfohlen)

# MCP Server hinzufügen (Read-Only für Märchenzauber Production)
claude mcp add --transport http supabase-maerchenzauber "https://mcp.supabase.com/mcp?read_only=true&project_ref=dyywxrmonxoiojsjmymc"

# Alle MCP Server auflisten
claude mcp list

# Server entfernen (falls nötig)
claude mcp remove supabase-maerchenzauber

Option B: Manuelle Konfiguration

Erstelle oder bearbeite die MCP-Konfigurationsdatei:

Für lokales Scope (nur für dich in diesem Projekt):

# .mcp.json im Projekt-Root erstellen

Für User Scope (global für alle deine Projekte):

# ~/.config/claude/mcp.json

Konfiguration (JSON):

{
	"mcpServers": {
		"supabase-maerchenzauber": {
			"type": "http",
			"url": "https://mcp.supabase.com/mcp?read_only=true&project_ref=dyywxrmonxoiojsjmymc"
		}
	}
}

Schritt 3: Konfigurationsoptionen

URL-Parameter

Du kannst die MCP Server URL mit folgenden Query-Parametern anpassen:

https://mcp.supabase.com/mcp?read_only=true&project_ref=<projekt-ref>&features=database,debugging

Verfügbare Parameter:

• read_only=true - Nur Lesezugriff (empfohlen!)
• project_ref=<ref> - Beschränke auf spezifisches Projekt
• features=<gruppe1>,<gruppe2> - Aktiviere nur bestimmte Tool-Gruppen

Beispiele:

# Read-Only mit nur Database-Tools
https://mcp.supabase.com/mcp?read_only=true&project_ref=dyywxrmonxoiojsjmymc&features=database

# Voller Zugriff auf Development-Datenbank
https://mcp.supabase.com/mcp?project_ref=<dev-projekt-ref>

# Nur Debugging und Knowledge Base
https://mcp.supabase.com/mcp?read_only=true&project_ref=dyywxrmonxoiojsjmymc&features=debugging,knowledgebase

Schritt 4: Authentifizierung

Beim ersten Verwenden des MCP Servers wirst du automatisch aufgefordert, dich zu authentifizieren:

1. Browser-Fenster öffnet sich automatisch
2. Login bei Supabase mit deinem Account
3. Organisation auswählen, die das Projekt enthält
4. Zugriff gewähren für den MCP Server

Die Authentifizierung erfolgt über OAuth 2.0 und ist sicher.

Schritt 5: MCP Server verwenden

Nach der Einrichtung kannst du in Claude Code direkt mit der Datenbank interagieren:

Beispiel-Prompts

"Zeige mir alle Tabellen in der Märchenzauber-Datenbank"

"Erstelle eine neue Spalte 'created_at' in der 'stories' Tabelle"

"Wie viele Charaktere haben wir insgesamt in der Datenbank?"

"Analysiere die Struktur der 'characters' Tabelle"

"Führe eine Migration aus, um die 'user_settings' Tabelle zu erweitern"

MCP Resources verwenden

Du kannst auf Datenbank-Ressourcen mit @ verweisen:

"Analysiere @characters Tabelle und schlage Optimierungen vor"

Konfiguration für verschiedene Umgebungen

Development Setup (empfohlen für Start)

{
	"mcpServers": {
		"supabase-dev": {
			"type": "http",
			"url": "https://mcp.supabase.com/mcp?project_ref=dyywxrmonxoiojsjmymc&features=database,development"
		}
	}
}

Production Setup (nur Lesen)

{
	"mcpServers": {
		"supabase-prod": {
			"type": "http",
			"url": "https://mcp.supabase.com/mcp?read_only=true&project_ref=dyywxrmonxoiojsjmymc&features=database"
		}
	}
}

Debugging Setup

{
	"mcpServers": {
		"supabase-debug": {
			"type": "http",
			"url": "https://mcp.supabase.com/mcp?read_only=true&project_ref=dyywxrmonxoiojsjmymc&features=database,debugging"
		}
	}
}

Projekt-spezifische Informationen

Märchenzauber Supabase Details

• Projekt URL: https://dyywxrmonxoiojsjmymc.supabase.co
• Projekt Ref: dyywxrmonxoiojsjmymc
• Storage Bucket: maerchenzauber

Wichtige Tabellen

• characters - Benutzerdefinierte Charaktere
• stories - Generierte Geschichten
• story_collections - Story-Sammlungen
• user_settings - Benutzereinstellungen
• public_stories - Öffentlich geteilte Geschichten

Empfohlene MCP-Konfiguration für Märchenzauber

# Produktive Datenbank (Read-Only)
claude mcp add --transport http supabase-prod "https://mcp.supabase.com/mcp?read_only=true&project_ref=dyywxrmonxoiojsjmymc&features=database,knowledgebase"

# Development/Testing (mit Schreibrechten)
# ACHTUNG: Nur nutzen, wenn du eine Dev-Instanz hast!
# claude mcp add --transport http supabase-dev "https://mcp.supabase.com/mcp?project_ref=<dev-ref>&features=database,development,debugging"

Troubleshooting

MCP Server verbindet nicht

# 1. Überprüfe ob MCP konfiguriert ist
claude mcp list

# 2. Authentifizierung zurücksetzen
# Lösche die Authentifizierungsdaten und starte neu

# 3. Überprüfe die Projekt-Referenz
# Stelle sicher, dass dyywxrmonxoiojsjmymc korrekt ist

Queries schlagen fehl

• Read-Only Mode: Wenn read_only=true gesetzt ist, sind nur SELECT-Queries erlaubt
• Permissions: Überprüfe, ob dein Supabase-Account die nötigen Rechte hat
• RLS Policies: Row Level Security Policies können Queries blockieren

Authentifizierung schlägt fehl

• Stelle sicher, dass du im richtigen Supabase-Account eingeloggt bist
• Überprüfe, ob du Zugriff auf die Organisation hast, die das Projekt enthält
• Versuche, dich erneut zu authentifizieren

Erweiterte Konfiguration

Umgebungsvariablen verwenden

Du kannst Umgebungsvariablen in der MCP-Konfiguration nutzen:

{
	"mcpServers": {
		"supabase": {
			"type": "http",
			"url": "https://mcp.supabase.com/mcp?read_only=true&project_ref=${SUPABASE_PROJECT_REF}"
		}
	}
}

Mehrere Projekte

Du kannst mehrere Supabase-Projekte gleichzeitig konfigurieren:

{
	"mcpServers": {
		"supabase-maerchenzauber-prod": {
			"type": "http",
			"url": "https://mcp.supabase.com/mcp?read_only=true&project_ref=dyywxrmonxoiojsjmymc"
		},
		"supabase-maerchenzauber-dev": {
			"type": "http",
			"url": "https://mcp.supabase.com/mcp?project_ref=<dev-ref>"
		}
	}
}

Team-Setup (Project Scope)

Für Team-weite Konfiguration, erstelle .mcp.json im Projekt-Root:

{
	"mcpServers": {
		"supabase-maerchenzauber": {
			"type": "http",
			"url": "https://mcp.supabase.com/mcp?read_only=true&project_ref=dyywxrmonxoiojsjmymc&features=database",
			"description": "Märchenzauber Production DB (Read-Only)"
		}
	}
}

Vorteile:

• Alle Teammitglieder nutzen die gleiche Konfiguration
• Versionskontrolle über Git
• Einheitliche Development-Experience

Hinweis: Jedes Teammitglied muss sich individuell authentifizieren.

Nützliche Workflows

1. Datenbank-Schema analysieren

Claude: "Analysiere alle Tabellen in der Datenbank und erstelle ein Schema-Diagramm"

2. Migration erstellen

Claude: "Erstelle eine Migration, um eine 'is_favorite' Spalte zur 'stories' Tabelle hinzuzufügen"

3. Daten abfragen

Claude: "Zeige mir die letzten 10 erstellten Stories mit ihren Autoren"

4. Performance-Analyse

Claude: "Analysiere die Performance der 'characters' Tabelle und schlage Indizes vor"

Sicherheits-Checkliste

Vor der Einrichtung von MCP:

• Nutze niemals Production-Daten für Experimente
• Aktiviere Read-Only Mode für Production
• Beschränke auf spezifisches Projekt mit project_ref
• Aktiviere nur benötigte Features
• Nutze Database Branching für sichere Tests
• Teile niemals MCP-Konfiguration mit End-Usern
• Überprüfe regelmäßig die Zugriffe im Supabase Dashboard

Ressourcen

• Supabase MCP Documentation
• Supabase MCP GitHub
• Claude Code MCP Documentation
• Model Context Protocol Spec

Support

Bei Problemen:

1. Supabase Discord: Frage im #mcp Channel
2. GitHub Issues: supabase-community/supabase-mcp
3. Claude Code Issues: anthropics/claude-code

Version

• Dokument erstellt: 2025-10-15
• Supabase MCP Server: Pre-1.0 (Breaking Changes möglich)
• Claude Code: Latest

Changelog

• 2025-10-15: Initiale Dokumentation erstellt