MotherDucks DuckDB MCP-Server

Eine MCP-Serverimplementierung, die mit DuckDB- und MotherDuck-Datenbanken interagiert und KI-Assistenten und IDEs SQL-Analysefunktionen bietet.

Ressourcen

• Den Kreis schließen: Schnellere Datenpipelines mit MCP, DuckDB und KI (Blogbeitrag)

• Schnellere Entwicklung von Datenpipelines mit MCP und DuckDB (YouTube)

Merkmale

• Hybridausführung : Abfrage von Daten aus lokalen DuckDB- und/oder Cloud-basierten MotherDuck-Datenbanken

• Cloud-Speicherintegration : Zugriff auf Daten, die in Amazon S3 oder anderen Cloud-Speichern gespeichert sind, dank der Integrationen von MotherDuck

• Datenfreigabe : Erstellen und Freigeben von Datenbanken

• SQL-Analyse : Verwenden Sie den SQL-Dialekt von DuckDB, um Daten jeder Größe direkt von Ihrem KI-Assistenten oder Ihrer IDE abzufragen

• Serverlose Architektur : Führen Sie Analysen aus, ohne Instanzen oder Cluster konfigurieren zu müssen

Komponenten

Eingabeaufforderungen

Der Server bietet eine Eingabeaufforderung:

• duckdb-motherduck-initial-prompt : Eine Eingabeaufforderung zum Initialisieren einer Verbindung zu DuckDB oder MotherDuck und zum Starten der Arbeit damit

Werkzeuge

Der Server bietet ein Tool:

• query : Führen Sie eine SQL-Abfrage in der DuckDB- oder MotherDuck-Datenbank aus

  • Eingänge :

    • query (Zeichenfolge, erforderlich): Die auszuführende SQL-Abfrage

Alle Interaktionen mit DuckDB und MotherDuck erfolgen durch das Schreiben von SQL-Abfragen.

Erste Schritte

Allgemeine Voraussetzungen

• uv installiert ist, können Sie es mit pip install uv oder brew install uv installieren

Wenn Sie MCP mit Claude Desktop oder einem anderen MCP-kompatiblen Client verwenden möchten, muss der Client installiert werden.

Voraussetzungen für DuckDB

• Keine Voraussetzungen. Der MCP-Server kann im laufenden Betrieb eine In-Memory-Datenbank erstellen

• Oder stellen Sie eine Verbindung zu einer vorhandenen lokalen DuckDB-Datenbankdatei oder einer auf einem Remote-Objektspeicher (z. B. AWS S3) gespeicherten Datei her.

Siehe „Verbindung zur lokalen DuckDB herstellen“ .

Voraussetzungen für MotherDuck

• Registrieren Sie sich für ein MotherDuck-Konto

• Generieren Sie ein Zugriffstoken über die MotherDuck-Benutzeroberfläche

• Bewahren Sie das Token sicher auf, um es in der Konfiguration verwenden zu können

Verwendung mit Cursor

1. Installieren Sie Cursor von cursor.com/downloads, falls Sie dies noch nicht getan haben

2. Cursor öffnen:

• Um es zum ersten Mal global einzurichten, gehen Sie zu Einstellungen->MCP und klicken Sie auf „+ Neuen globalen MCP-Server hinzufügen“.

• Dadurch wird eine mcp.json Datei geöffnet, zu der Sie die folgende Konfiguration hinzufügen:

Verwendung mit VS Code

1. Klicken Sie für die schnellste Installation oben in dieser README-Datei auf eine der Schaltflächen „Mit UV installieren“.

Manuelle Installation

Fügen Sie den folgenden JSON-Block zu Ihrer Benutzereinstellungsdatei (JSON) in VS Code hinzu. Drücken Sie dazu Ctrl + Shift + P und geben Sie Preferences: Open User Settings (JSON) ein.

Optional können Sie es einer Datei namens .vscode/mcp.json in Ihrem Arbeitsbereich hinzufügen. Dadurch können Sie die Konfiguration mit anderen teilen.

Verwendung mit Claude Desktop

1. Installieren Sie Claude Desktop von claude.ai/download , falls Sie dies noch nicht getan haben

2. Öffnen Sie die Claude Desktop-Konfigurationsdatei:

• Um schnell darauf zuzugreifen oder es zum ersten Mal zu erstellen, öffnen Sie die Claude Desktop-App, wählen Sie „Einstellungen“ und klicken Sie auf die Registerkarte „Entwickler“. Klicken Sie schließlich auf die Schaltfläche „Konfiguration bearbeiten“.

• Fügen Sie Ihrer claude_desktop_config.json die folgende Konfiguration hinzu:

Wichtige Hinweise :

• Ersetzen Sie YOUR_MOTHERDUCK_TOKEN_HERE durch Ihr tatsächliches MotherDuck-Token

• Ersetzen Sie YOUR_HOME_FOLDER_PATH durch den Pfad zu Ihrem Home-Verzeichnis (wird von DuckDB für Dateioperationen benötigt). Unter macOS wäre dies beispielsweise /Users/your_username

• Die Umgebungsvariable HOME ist für die ordnungsgemäße Funktion von DuckDB erforderlich.

Sichern Ihres MCP-Servers bei der Abfrage von MotherDuck

Wenn der MCP-Server Dritten zugänglich ist und nur Lesezugriff auf Daten haben soll, empfehlen wir die Verwendung eines Lese-Skalierungstokens und die Ausführung des MCP-Servers im SaaS-Modus.

Leseskalierungstoken sind spezielle Zugriffstoken, die skalierbare Lesevorgänge ermöglichen. Sie erlauben bis zu vier gleichzeitige Lese-Replikate. Dies verbessert die Leistung für mehrere Endbenutzer und schränkt gleichzeitig die Schreibfunktionen ein . Informationen zum Erstellen eines Leseskalierungstokens finden Sie in der Dokumentation zur Leseskalierung .

Der SaaS-Modus in MotherDuck erhöht die Sicherheit durch eingeschränkten Zugriff auf lokale Dateien, Datenbanken, Erweiterungen und Konfigurationen. Dadurch eignet er sich ideal für Drittanbieter-Tools, die einen strengeren Umgebungsschutz erfordern. Weitere Informationen finden Sie in der SaaS-Modus-Dokumentation .

Sichere Konfiguration

Verbindung zur lokalen DuckDB herstellen

Um eine Verbindung zu einer lokalen DuckDB herzustellen, geben Sie anstelle des MotherDuck-Tokens den Pfad zu Ihrer lokalen DuckDB-Datenbankdatei an oder verwenden Sie :memory: für eine In-Memory-Datenbank.

In-Memory-Datenbank:

Lokale DuckDB-Datei:

Lokale DuckDB-Datei im schreibgeschützten Modus :

Hinweis : Der Nur-Lese-Modus für lokale, dateibasierte DuckDB-Verbindungen nutzt auch kurzlebige Verbindungen. Bei jeder Verwendung des MCP-Abfragetools wird eine temporäre, schreibgeschützte Verbindung hergestellt, die Abfrage ausgeführt und die Verbindung geschlossen. Diese Funktion entstand durch einen Workflow, bei dem DBT zur Datenmodellierung innerhalb von DuckDB diente und anschließend ein MCP-Client (Windsurf/Cline/Claude/Cursor) zur Datenbankerkundung verwendet wurde. Die kurzlebigen Verbindungen ermöglichen es jedem Tool, zu laufen und anschließend die Verbindung freizugeben, sodass das nächste Tool eine Verbindung herstellen kann.

Beispielabfragen

Nach der Konfiguration können Sie Claude beispielsweise bitten, Abfragen wie die folgenden auszuführen:

• „Erstellen Sie eine neue Datenbank und Tabelle in MotherDuck“

• „Daten aus meiner lokalen CSV-Datei abfragen“

• „Daten aus meiner lokalen DuckDB-Datenbank mit einer Tabelle in MotherDuck verknüpfen“

• „In Amazon S3 gespeicherte Daten analysieren“

Testen

Der Server ist für den Betrieb mit Tools wie Claude Desktop und Cursor ausgelegt, kann aber zu Testzwecken auch manuell gestartet werden. Beim manuellen Testen des Servers können Sie mit dem Parameter --db-path angeben, mit welcher Datenbank eine Verbindung hergestellt werden soll:

1. Standard-MotherDuck-Datenbank :

   • Um eine Verbindung mit der Standarddatenbank von MotherDuck herzustellen, müssen Sie das Authentifizierungstoken mit dem Parameter --motherduck-token übergeben.

   uvx mcp-server-motherduck --db-path md: --motherduck-token <your_motherduck_token>

2. Spezifische MotherDuck-Datenbank :

   uvx mcp-server-motherduck --db-path md:your_database_name --motherduck-token <your_motherduck_token>

3. Lokale DuckDB-Datenbank :

   uvx mcp-server-motherduck --db-path /path/to/your/local.db

4. In-Memory-Datenbank :

   uvx mcp-server-motherduck --db-path :memory:

Wenn Sie keinen Datenbankpfad angeben, aber die Umgebungsvariable motherduck_token festgelegt haben, stellt der Server automatisch eine Verbindung zur Standarddatenbank von MotherDuck ( md: ) her.

Ausführung im SSE-Modus

Der Server könnte auch den SSE-Modus mit supergateway ausführen, indem Sie den folgenden Befehl ausführen:

Und Sie können Ihre Clients wie Claude Desktop und Cursor auf diesen Endpunkt richten.

Entwicklungskonfiguration

Um den Server aus einer lokalen Entwicklungsumgebung auszuführen, verwenden Sie die folgende Konfiguration:

Fehlerbehebung

• Wenn Verbindungsprobleme auftreten, überprüfen Sie, ob Ihr MotherDuck-Token korrekt ist

• Stellen Sie bei Problemen mit dem lokalen Dateizugriff sicher, dass der Parameter --home-dir richtig eingestellt ist

• Überprüfen Sie, ob der Befehl uvx in Ihrem PATH verfügbar ist

• Wenn spawn uvx ENOENT Fehler auftreten, versuchen Sie, den vollständigen Pfad zu uvx anzugeben ( which uvx ).

• In der vorherigen Version v0.4.0 haben wir Umgebungsvariablen verwendet, jetzt verwenden wir Parameter

Lizenz

Dieser MCP-Server ist unter der MIT-Lizenz lizenziert. Das bedeutet, dass Sie die Software unter den Bedingungen der MIT-Lizenz frei verwenden, ändern und verbreiten dürfen. Weitere Informationen finden Sie in der LICENSE-Datei im Projekt-Repository.