MotherDuck

DuckDB / MotherDuck Local MCP Server

SQL-Analysen und Data Engineering für KI-Assistenten und IDEs.

Verbinden Sie KI-Assistenten mit Ihren Daten mithilfe der leistungsstarken analytischen SQL-Engine von DuckDB. Unterstützt die Verbindung zu lokalen DuckDB-Dateien, In-Memory-Datenbanken, S3-gehosteten Datenbanken und MotherDuck. Ermöglicht das Ausführen von SQL-Lese- und Schreibabfragen, das Durchsuchen von Datenbankkatalogen und das Wechseln zwischen verschiedenen Datenbankverbindungen im laufenden Betrieb.

Auf der Suche nach einem vollständig verwalteten Remote-MCP-Server für MotherDuck? → Gehen Sie zur MotherDuck Remote MCP-Dokumentation

Remote vs. Local MCP

Schnellstart

Voraussetzungen: Installieren Sie uv über pip install uv oder brew install uv

Verbindung zu In-Memory DuckDB (Entwicklungsmodus)

{
  "mcpServers": {
    "DuckDB (in-memory, r/w)": {
      "command": "uvx",
      "args": ["mcp-server-motherduck", "--db-path", ":memory:", "--read-write", "--allow-switch-databases"]
    }
  }
}

Volle Flexibilität ohne Einschränkungen — Lese-/Schreibzugriff und die Möglichkeit, zur Laufzeit zu jeder Datenbank (lokale Dateien, S3 oder MotherDuck) zu wechseln.

Verbindung zu einer lokalen DuckDB-Datei im Nur-Lese-Modus

{
  "mcpServers": {
    "DuckDB (read-only)": {
      "command": "uvx",
      "args": ["mcp-server-motherduck", "--db-path", "/absolute/path/to/your.duckdb"]
    }
  }
}

Stellt eine Verbindung zu einer bestimmten DuckDB-Datei im Nur-Lese-Modus her. Hält die Dateisperre nicht fest, sodass sie bequem neben einer Schreibverbindung zu derselben DuckDB-Datei verwendet werden kann. Sie können auch über s3://bucket/path.duckdb eine Verbindung zu Remote-DuckDB-Dateien auf S3 herstellen — siehe Umgebungsvariablen für die S3-Authentifizierung. Wenn Sie den Zugriff Dritter auf das MCP in Betracht ziehen, siehe Absicherung für die Produktion.

Verbindung zu MotherDuck im Lese-/Schreibmodus

{
  "mcpServers": {
    "MotherDuck (local, r/w)": {
      "command": "uvx",
      "args": ["mcp-server-motherduck", "--db-path", "md:", "--read-write"],
      "env": {
        "motherduck_token": "<YOUR_MOTHERDUCK_TOKEN>"
      }
    }
  }
}

Siehe Befehlszeilenparameter für weitere Optionen, Absicherung für die Produktion für Bereitstellungsanleitungen und Fehlerbehebung, wenn Probleme auftreten.

Client-Einrichtung

Client	Konfigurationsspeicherort	Ein-Klick-Installation
Claude Desktop	Einstellungen → Entwickler → Konfiguration bearbeiten	.mcpb (MCP-Bundle)
Claude Code	Verwenden Sie die CLI-Befehle unten	-
Codex CLI	Verwenden Sie die CLI-Befehle unten oder ~/.codex/config.toml	-
Gemini CLI	Verwenden Sie die CLI-Befehle unten oder ~/.gemini/settings.json	-
Cursor	Einstellungen → MCP → Neuen globalen MCP-Server hinzufügen
VS Code	Ctrl+Shift+P → "Einstellungen: Benutzereinstellungen (JSON) öffnen"
Kiro	~/.kiro/settings/mcp.json (global) oder .kiro/settings/mcp.json (Projekt)

Jeder MCP-kompatible Client kann diesen Server verwenden. Fügen Sie die JSON-Konfiguration aus Schnellstart zur MCP-Konfigurationsdatei Ihres Clients hinzu. Konsultieren Sie die Dokumentation Ihres Clients für den Speicherort der Konfigurationsdatei.

claude mcp add --scope user duckdb --transport stdio -- uvx mcp-server-motherduck --db-path :memory: --read-write --allow-switch-databases

claude mcp add --scope user duckdb --transport stdio -- uvx mcp-server-motherduck --db-path /absolute/path/to/db.duckdb

claude mcp add --scope user motherduck --transport stdio --env motherduck_token=YOUR_TOKEN -- uvx mcp-server-motherduck --db-path md: --read-write

codex mcp add duckdb -- uvx mcp-server-motherduck --db-path :memory: --read-write --allow-switch-databases

codex mcp add duckdb -- uvx mcp-server-motherduck --db-path /absolute/path/to/db.duckdb

codex mcp add motherduck --env motherduck_token=YOUR_TOKEN -- uvx mcp-server-motherduck --db-path md: --read-write

gemini mcp add -s user duckdb uvx mcp-server-motherduck --db-path :memory: --read-write --allow-switch-databases

gemini mcp add -s user duckdb uvx mcp-server-motherduck --db-path /absolute/path/to/db.duckdb

gemini mcp add -s user -e motherduck_token=YOUR_TOKEN motherduck uvx mcp-server-motherduck --db-path md: --read-write

{
  "mcpServers": {
    "DuckDB (in-memory, r/w)": {
      "command": "uvx",
      "args": ["mcp-server-motherduck", "--db-path", ":memory:", "--read-write", "--allow-switch-databases"]
    }
  }
}

{
  "mcpServers": {
    "MotherDuck (local, r/w)": {
      "command": "uvx",
      "args": ["mcp-server-motherduck", "--db-path", "md:", "--read-write"],
      "env": {
        "motherduck_token": "<YOUR_MOTHERDUCK_TOKEN>"
      }
    }
  }
}

Tools

*Erfordert das --allow-switch-databases-Flag

Alle Tools geben JSON zurück. Ergebnisse sind standardmäßig auf 1024 Zeilen / 50.000 Zeichen begrenzt (konfigurierbar über --max-rows, --max-chars).

Absicherung für die Produktion

Wenn Sie Dritten Zugriff auf einen selbst gehosteten MCP-Server gewähren, reicht der Nur-Lese-Modus allein nicht aus — er ermöglicht weiterhin Zugriff auf das lokale Dateisystem, das Ändern von DuckDB-Einstellungen und andere potenziell sensible Vorgänge.

Für Produktionsbereitstellungen mit Zugriff Dritter empfehlen wir MotherDuck Remote MCP — keine Einrichtung erforderlich, Lese-/Schreibfähig und von MotherDuck gehostet.

Selbst gehostetes MotherDuck-MCP: Forken Sie dieses Repository und passen Sie es nach Bedarf an. Verwenden Sie ein Dienstkonto mit Lese-Skalierungs-Tokens und aktivieren Sie den SaaS-Modus, um den lokalen Dateizugriff einzuschränken.

Selbst gehostetes DuckDB-MCP: Verwenden Sie --init-sql, um Sicherheitseinstellungen anzuwenden. Siehe die Anleitung zur DuckDB-Absicherung für verfügbare Optionen.

Docker

Erstellen und starten Sie den Server mit Streamable HTTP auf Port 8000 (standardmäßig eine In-Memory-DuckDB):

docker build -t mcp-server-motherduck .
docker run --rm -p 8000:8000 mcp-server-motherduck

Verbinden Sie sich mit MotherDuck, indem Sie ein Token übergeben und den Befehl überschreiben:

docker run --rm -p 8000:8000 \
  -e motherduck_token="$MOTHERDUCK_TOKEN" \
  mcp-server-motherduck --transport http --db-path md:

Der MCP-Endpunkt ist unter http://localhost:8000/mcp verfügbar. CLI-Flags und Umgebungsvariablen von unten gelten weiterhin.

Befehlszeilenparameter

Umgebungsvariablen

Fehlerbehebung

• spawn uvx ENOENT: Geben Sie den vollständigen Pfad zu uvx an (führen Sie which uvx aus, um ihn zu finden)
• Datei gesperrt: Stellen Sie sicher, dass --ephemeral-connections aktiviert ist (Standard: true) und dass Sie nicht im Lese-/Schreibmodus verbunden sind

Ressourcen

• MotherDuck-MCP-Dokumentation
• Close the Loop: Schnellere Datenpipelines mit MCP, DuckDB & KI (Blog)
• Schnellere Datenpipelines mit MCP und DuckDB (YouTube)

Entwicklung

Zum Ausführen aus dem Quellcode:

{
  "mcpServers": {
    "Local DuckDB (Dev)": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-server-motherduck", "run", "mcp-server-motherduck", "--db-path", "md:"],
      "env": {
        "motherduck_token": "<YOUR_MOTHERDUCK_TOKEN>"
      }
    }
  }
}

Release-Prozess

1. Führen Sie die Release New Version-GitHub-Action aus
2. Geben Sie die Version im Format MAJOR.MINOR.PATCH ein
3. Der Workflow erhöht die Version, veröffentlicht auf PyPI/MCP-Registry und erstellt das GitHub-Release mit dem MCPB-Paket

Lizenz

MIT-Lizenz — siehe LICENSE-Datei.

mcp-name: io.github.motherduckdb/mcp-server-motherduck