MotherDuck MCP Server

DuckDB / MotherDuck Lokaler MCP-Server

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

Verbinden Sie KI-Assistenten mit Ihren Daten unter Verwendung 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 die Ausführung von SQL-Lese- und Schreibabfragen, das Durchsuchen von Datenbankkatalogen und das dynamische Wechseln zwischen verschiedenen Datenbankverbindungen.

Suchen Sie einen vollständig verwalteten Remote-MCP-Server für MotherDuck? → Zur MotherDuck Remote MCP-Dokumentation

Remote vs. Lokaler MCP

📝 Migration von v0.x?

• Standardmäßig schreibgeschützt: Der Server läuft jetzt standardmäßig im schreibgeschützten Modus. Fügen Sie --read-write hinzu, um Schreibzugriff zu aktivieren. Siehe Absicherung für die Produktion.
• Standarddatenbank geändert: Der Standardwert von --db-path wurde von md: auf :memory: geändert. Fügen Sie --db-path md: explizit für MotherDuck hinzu.
• MotherDuck schreibgeschützt erfordert Read-Scaling-Token: MotherDuck-Verbindungen im schreibgeschützten Modus erfordern ein Read-Scaling-Token. Reguläre Token erfordern --read-write.

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 einer beliebigen Datenbank (lokale Dateien, S3 oder MotherDuck) zu wechseln.

Verbindung zu einer lokalen DuckDB-Datei im schreibgeschützten 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 schreibgeschützten Modus her. Hält die Dateisperre nicht aufrecht, sodass die gleichzeitige Nutzung mit einer Schreibverbindung zur selben DuckDB-Datei bequem möglich ist. Sie können auch eine Verbindung zu entfernten DuckDB-Dateien auf S3 herstellen, indem Sie s3://bucket/path.duckdb verwenden – siehe Umgebungsvariablen für die S3-Authentifizierung. Wenn Sie Drittzugriff auf den MCP in Betracht ziehen, lesen Sie 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 Kommandozeilenparameter für weitere Optionen, Absicherung für die Produktion für Bereitstellungshinweise und Fehlerbehebung, falls Probleme auftreten.

Client-Einrichtung

Client	Konfigurationsort	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 dem 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>"
      }
    }
  }
}

Werkzeuge

*Erfordert das Flag --allow-switch-databases

Alle Werkzeuge 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, ist der schreibgeschützte Modus allein nicht ausreichend – er ermöglicht weiterhin den Zugriff auf das lokale Dateisystem, das Ändern von DuckDB-Einstellungen und andere potenziell sensible Vorgänge.

Für Produktionsbereitstellungen mit Drittzugriff empfehlen wir MotherDuck Remote MCP – keine Einrichtung, Lese-/Schreibfähigkeit und von MotherDuck gehostet.

Selbst-Hosting von MotherDuck MCP: Forken Sie dieses Repository und passen Sie es nach Bedarf an. Verwenden Sie ein Servicekonto mit Read-Scaling-Token und aktivieren Sie den SaaS-Modus, um den lokalen Dateizugriff einzuschränken.

Selbst-Hosting von DuckDB MCP: Verwenden Sie --init-sql, um Sicherheitseinstellungen anzuwenden. Siehe den Leitfaden zur DuckDB-Absicherung für verfügbare Optionen.

Kommandozeilenparameter

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

Ausführung 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