mcp-server-motherduck

MotherDucks DuckDB MCP-Server

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

Ressourcen

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

Installieren Sie Cursor von cursor.com/downloads, falls Sie dies noch nicht getan haben
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:

{
  "mcpServers": {
    "mcp-server-motherduck": {
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--db-path",
        "md:",
        "--motherduck-token",
        "<YOUR_MOTHERDUCK_TOKEN_HERE>"
      ]
    }
  }
}

Verwendung mit VS Code

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.

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "motherduck_token",
        "description": "MotherDuck Token",
        "password": true
      }
    ],
    "servers": {
      "motherduck": {
        "command": "uvx",
        "args": [
          "mcp-server-motherduck",
          "--db-path",
          "md:",
          "--motherduck-token",
          "${input:motherduck_token}"
        ]
      }
    }
  }
}

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.

{
  "inputs": [
    {
      "type": "promptString",
      "id": "motherduck_token",
      "description": "MotherDuck Token",
      "password": true
    }
  ],
  "servers": {
    "motherduck": {
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--db-path",
        "md:",
        "--motherduck-token",
        "${input:motherduck_token}"
      ]
    }
  }
}

Verwendung mit Claude Desktop

Installieren Sie Claude Desktop von claude.ai/download , falls Sie dies noch nicht getan haben
Ö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:

{
  "mcpServers": {
    "mcp-server-motherduck": {
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--db-path",
        "md:",
        "--motherduck-token",
        "<YOUR_MOTHERDUCK_TOKEN_HERE>"
      ]
    }
  }
}

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

{
  "mcpServers": {
    "mcp-server-motherduck": {
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--db-path",
        "md:",
        "--motherduck-token",
        "<YOUR_READ_SCALING_TOKEN_HERE>",
        "--saas-mode"
      ]
    }
  }
}

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:

{
  "mcpServers": {
    "mcp-server-motherduck": {
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--db-path",
        ":memory:"
      ]
    }
  }
}

Lokale DuckDB-Datei:

{
  "mcpServers": {
    "mcp-server-motherduck": {
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--db-path",
        "/path/to/your/local.db"
      ]
    }
  }
}

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:

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>
Spezifische MotherDuck-Datenbank :
uvx mcp-server-motherduck --db-path md:your_database_name --motherduck-token <your_motherduck_token>
Lokale DuckDB-Datenbank :
uvx mcp-server-motherduck --db-path /path/to/your/local.db
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:

npx -y supergateway --stdio "uvx mcp-server-motherduck --db-path md: --motherduck-token <your_motherduck_token>"

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:

 {
  "mcpServers": {
    "mcp-server-motherduck": {
      "command": "uv",
      "args": [
        "--directory", 
        "/path/to/your/local/mcp-server-motherduck", 
        "run", 
        "mcp-server-motherduck", 
        "--db-path",
        "md:",
        "--motherduck-token",
        "<YOUR_MOTHERDUCK_TOKEN_HERE>"
      ]
    }
  }
}

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.