MCP Firebase Server

MCP Firebase-Server (Model Context Protocol)

Dieser Server implementiert das Model Context Protocol (MCP) als Brücke zwischen einem Large Language Model (LLM) wie Claude und Firebase (Firestore). Es ermöglicht dem LLM, Firestore-Sammlungen zu lesen und zu beschreiben, indem diese Operationen als MCP-Tools bereitgestellt werden.

Dieser Server wurde mit dem offiziellen mcp Python SDK erstellt.

Voraussetzungen

• Python 3.7+ (vorzugsweise 3.8+ für asynccontextmanager und vollständige Type-Hinting-Funktionen, die von MCP verwendet werden)
• Pip (Python-Paketinstallationsprogramm) oder uv (von MCP-Dokumenten für Projektmanagement empfohlen)
• Ein Firebase-Projekt mit aktiviertem Firestore.
• Eine JSON-Datei mit dem Firebase-Dienstkontoschlüssel.

Aufstellen

1. Klonen/Herunterladen: Stellen Sie sicher, dass Sie die Serverdatei ( mcp_firebase_server.py ), requirements.txt usw. in einem lokalen Verzeichnis haben.
2. Dienstkontoschlüssel:
   • Der Server benötigt zur Authentifizierung einen Firebase-Dienstkontoschlüssel.
   • Option 1 (empfohlen für die MCP-Client-Konfiguration): Setzen Sie die Umgebungsvariable SERVICE_ACCOUNT_KEY_PATH auf den absoluten Pfad Ihrer JSON-Datei des Dienstkontos. Dies ist die flexibelste Methode, wenn der Server von einem MCP-Client gestartet wird.
   • Option 2 (Fallback): Wenn die Umgebungsvariable SERVICE_ACCOUNT_KEY_PATH nicht gesetzt ist, sucht der Server in seinem eigenen Verzeichnis (demselben Verzeichnis wie mcp_firebase_server.py ) nach einer Datei namens serviceAccountKey.json . Benennen Sie bei dieser Methode Ihre Schlüsseldatei entsprechend um.
   • Wichtig: Stellen Sie sicher, dass Ihre Dienstkonto-Schlüsseldatei (unabhängig von ihrem Namen oder Zugriff) sicher aufbewahrt und idealerweise in Ihrer .gitignore Datei aufgeführt wird, wenn im Projekt eine lokale Kopie vorhanden ist.
3. Firebase-Speicher-Bucket (optional):
   • Wenn Sie Firebase Storage-Funktionen mit diesem Server nutzen möchten (derzeit wird dies von keinem Tool verwendet, kann aber hinzugefügt werden), setzen Sie die Umgebungsvariable FIREBASE_STORAGE_BUCKET auf den Namen des Storage Buckets Ihres Firebase-Projekts (z. B. your-project-id.appspot.com ). Der Server liest und gibt diesen Wert aus, wenn dieser gesetzt ist.
4. Erstellen Sie eine virtuelle Umgebung (empfohlen): Verwenden von venv :
   python3 -m venv venv source venv/bin/activate # On macOS/Linux # venv\\Scripts\\activate # On Windows
   Oder bei Verwendung von uv (wie in den MCP-Dokumenten für neue Projekte vorgeschlagen):
   uv venv source .venv/bin/activate # Or similar, depending on your uv setup
5. Abhängigkeiten installieren: Verwenden von pip :
   pip install -r requirements.txt
   Oder, wenn Sie uv verwenden:
   uv pip install -r requirements.txt
   Dadurch werden mcp[cli] und firebase-admin installiert.

Ausführen des Servers

Es gibt mehrere Möglichkeiten, diesen MCP-Server auszuführen:

1. Direkte Ausführung (für stdio-Transport über run_server.sh ): Ein run_server.sh -Skript vereinfacht den Serverstart. Dieses Skript übernimmt die Aktivierung der virtuellen Umgebung (sofern sie venv heißt und im Projektstammverzeichnis vorhanden ist), bevor das Python-Skript ausgeführt wird.Machen Sie zunächst das Skript ausführbar:
   chmod +x run_server.sh
   Führen Sie dann den Server mit dem Skript aus:
   ./run_server.sh
   So würde ein MCP-Client normalerweise konfiguriert werden, um den Server zu starten (siehe Abschnitt „Verwendung mit Claude“ weiter unten).
2. **Verwendung der MCP-CLI für Entwicklung und Inspektion ( mcp dev ): Die mcp CLI (installiert als Teil von mcp[cli] ) stellt einen Entwicklungsserver und ein Inspektionstool bereit. Dies wird während der Entwicklung dringend empfohlen.
   mcp dev mcp_firebase_server.py
   Dadurch wird der Server gestartet und häufig wird eine Weboberfläche bereitgestellt, über die Sie seine Funktionen (Tools, Ressourcen) überprüfen und Testanrufe tätigen können.

Offengelegte MCP-Tools

Dieser Server mit dem Namen MCPFirebaseServer stellt die folgenden Tools bereit:

1. query_firestore_collection

• Beschreibung (aus der Dokumentzeichenfolge): Ruft Dokumente aus einer angegebenen Firestore-Sammlung ab.
• Argumente:
  • collection_name (Zeichenfolge, erforderlich): Der Name der abzufragenden Firestore-Sammlung.
  • limit (Ganzzahl, optional, Standard: 50): Die maximale Anzahl der zurückzugebenden Dokumente.
• Rückgabewert: (Liste[Dict[str, Any]]) Eine Liste von Dokumenten aus der Sammlung. Jedes Dokument ist ein Wörterbuch mit einem id Feld. Gibt eine Liste mit einem einzelnen Fehlerwörterbuch zurück, wenn ein Fehler auftritt (z. [{"error": "Firestore not initialized..."}] oder [{"error": "Failed to query..."}] ).

2. Dokument add_document_to_firestore

• Beschreibung (aus der Dokumentzeichenfolge): Fügt der angegebenen Firestore-Sammlung ein neues Dokument mit einer automatisch generierten ID hinzu.
• Argumente:
  • collection_name (Zeichenfolge, erforderlich): Der Name der Firestore-Sammlung, zu der das Dokument hinzugefügt wird.
  • document_data (Objekt/Wörterbuch, erforderlich): Ein Wörterbuch, das das hinzuzufügende Dokument darstellt.
• Rückgabewert: (Dict[str, Any]) Ein Wörterbuch, success (Boolescher Wert) und bei Erfolg entweder id (String) und message (String) oder bei Misserfolg error (String) enthält. Beispiel für Erfolg: {"success": True, "id": "newDocId", "message": "Document added to 'logs'"} Beispiel für Misserfolg: {"success": False, "error": "Firestore not initialized..."}

Verwendung mit Claude (oder anderen MCP-Clients)

Dieser MCP Firebase-Server ist als separater Prozess konzipiert und wird typischerweise von einer MCP-Client-Anwendung (z. B. Claude Desktop oder einer benutzerdefinierten Anwendung, die mit einer Plattform wie Windsurf erstellt wurde, die MCP-Server verwalten kann) gestartet. Der Client kommuniziert dann mit diesem Server, üblicherweise über stdio (Standard Input/Output) für lokal ausgeführte Server.

Allgemeine Integrationsschritte:

1. Serververfügbarkeit: Stellen Sie sicher, dass mcp_firebase_server.py und seine Abhängigkeiten (einschließlich serviceAccountKey.json ) auf dem System zugänglich sind, auf dem der MCP-Client ausgeführt wird oder Prozesse starten kann.
2. Client-Konfiguration: Die MCP-Client-Anwendung muss konfiguriert werden, um den Start Ihres MCPFirebaseServer zu ermöglichen. Diese Konfiguration umfasst in der Regel die Angabe von:
   • Ein auszuführender Befehl (z. B. python oder uv run python ).
   • Argumente für diesen Befehl (z. B. der Pfad zu mcp_firebase_server.py ).
   • Optional alle Umgebungsvariablen, die der Server möglicherweise benötigt (obwohl unser aktueller Server serviceAccountKey.json im selben Verzeichnis erwartet, könnte eine Umgebungsvariable für den Schlüsselpfad eine Alternative sein).
3. Einführung und Kommunikation:
   • Wenn der MCP-Client ein von diesem Server bereitgestelltes Tool verwenden muss, startet er mcp_firebase_server.py mit dem konfigurierten Befehl.
   • Client und Server kommunizieren dann über das MCP-Protokoll (z. B. über stdio ). Der Client kann verfügbare Tools ( query_firestore_collection , add_document_to_firestore ) ermitteln und aufrufen.

Beispiel für eine konzeptionelle Konfiguration (für einen MCP-Client wie Claude Desktop):

Viele MCP-kompatible Clientanwendungen (wie Claude Desktop, wie in der MCP-Dokumentation erwähnt) verwenden eine Konfigurationsdatei (häufig JSON), um zu definieren, wie MCP-Server gestartet und verwaltet werden. Das genaue Format kann je nach Client variieren, das Prinzip ist jedoch ähnlich.

Nachfolgend finden Sie ein konzeptionelles Beispiel basierend auf Mustern aus der MCP-Dokumentation. Sie müssen es an den spezifischen Konfigurationsmechanismus Ihres gewählten MCP-Clients (Claude Desktop, Windsurf usw.) anpassen.

Wichtige Punkte zur Konfiguration:

• "command" : Die auszuführende ausführbare Datei (z. B. python ). Stellen Sie sicher, dass sie sich im Pfad des Systems befindet, oder geben Sie den vollständigen Pfad zum Python-Interpreter an.
• "args" : Eine Liste von Argumenten. Das erste Argument ist typischerweise das auszuführende Skript. Es ist wichtig, den vollständigen, absoluten Pfad zu mcp_firebase_server.py zu verwenden, um sicherzustellen, dass der Client es finden kann, unabhängig davon, von wo aus der Client selbst gestartet wird.
• "cwd" (Aktuelles Arbeitsverzeichnis) : Manchmal müssen Sie möglicherweise das Arbeitsverzeichnis für den Serverprozess angeben, insbesondere wenn dieser auf relativen Pfaden für andere Dateien basiert (obwohl unser serviceAccountKey.json -Pfad relativ zum Skript selbst ist, was im Allgemeinen robust ist, wenn der Skriptpfad absolut ist).
• "env" : Zum Übergeben von Umgebungsvariablen. Während unser aktueller Server serviceAccountKey.json relativ zu seinem eigenen Pfad lokalisiert, besteht ein gängiges Muster für konfigurierbarere Server darin, Anmeldepfade oder andere Einstellungen über Umgebungsvariablen zu übergeben.

Interaktionsfluss (Zusammenfassung):

1. Client startet Server: Der MCP-Client (mit der obigen Konfiguration) startet mcp_firebase_server.py .
2. Server initialisiert: Unser Server versucht, eine Verbindung zu Firebase herzustellen.
3. Tool-Erkennung und -Aufrufe: Der Client erkennt und ruft nach Bedarf Tools wie query_firestore_collection oder add_document_to_firestore auf.
4. Server antwortet: Ergebnisse werden über stdio an den Client zurückgesendet.

Spezielle Anweisungen für Claude Desktop oder Windsurf:

• Claude Desktop: Wenn Sie Claude Desktop verwenden, lesen Sie in der Dokumentation nach, wie Sie benutzerdefinierte MCP-Server hinzufügen und konfigurieren. Die obige JSON-Struktur ist ein gängiges Muster, das Sie anpassen können.
• Windsurf: Wenn Windsurf Ihr Orchestrator ist und die Verwaltung von MCP-Servern unterstützt, verfügt es über eine eigene Methode zum Definieren und Starten dieser externen Tool-Server. Einzelheiten entnehmen Sie bitte der Windsurf-Dokumentation. Die Kerninformationen (Befehl, Argumente zum Ausführen mcp_firebase_server.py ) sind jedoch identisch.

Wenn Ihr Client keine dedizierte UI/Konfigurationsdatei zur MCP-Serververwaltung hat, aber Shell-Befehle ausführen und über stdio interagieren kann, würden Sie das Skript mcp_firebase_server.py programmgesteuert starten und dann eine MCP-Clientbibliothek (wie die in mcp.client.stdio ) verwenden, um mit ihm zu kommunizieren.

Entwicklung und Tests

• Verwenden Sie mcp dev mcp_firebase_server.py um den Server mit dem MCP Inspector auszuführen. So können Sie erkannte Tools sehen und interaktiv testen.
• Stellen Sie sicher, dass serviceAccountKey.json richtig platziert ist ODER die Umgebungsvariable SERVICE_ACCOUNT_KEY_PATH festgelegt ist, wenn der Server von einem MCP-Client gestartet wird.
• Überprüfen Sie die Konsolenausgabe des Servers auf Firebase-Initialisierungsmeldungen und etwaige Laufzeitfehler.

Das Skript run_server.sh :

Das Skript run_server.sh im Projektstammverzeichnis dient dazu:

1. Bestimmen Sie den eigenen Speicherort und ändern Sie das aktuelle Verzeichnis dorthin.
2. Suchen und aktivieren Sie eine virtuelle Python-Umgebung mit dem Namen venv , sofern diese im Projektstammverzeichnis vorhanden ist.
3. Führen Sie das Skript mcp_firebase_server.py mit dem python -Interpreter aus (idealerweise vom aktivierten Venv).

Dieses Skript stellt sicher, dass der MCP-Server in der vorgesehenen Umgebung ausgeführt wird. Denken Sie daran, es ausführbar zu machen ( chmod +x run_server.sh ).