mcp-server-duckdb

Eine Model Context Protocol (MCP)-Serverimplementierung für DuckDB, die Datenbankinteraktionsmöglichkeiten über MCP-Tools bietet. Eine Analyse durch LLM wäre interessant. DuckDB eignet sich für lokale Analysen.

Überblick

Dieser Server ermöglicht die Interaktion mit einer DuckDB-Datenbank über das Model Context Protocol und ermöglicht Datenbankoperationen wie Abfragen, Tabellenerstellung und Schemaprüfung.

Related MCP server: MotherDuck DuckDB MCP Server

Komponenten

Ressourcen

Derzeit sind keine benutzerdefinierten Ressourcen implementiert.

Eingabeaufforderungen

Derzeit sind keine benutzerdefinierten Eingabeaufforderungen implementiert.

Werkzeuge

Der Server implementiert das folgende Datenbankinteraktionstool:

• Abfrage : Führen Sie eine beliebige SQL-Abfrage in der DuckDB-Datenbank aus

  • Eingabe : query (Zeichenfolge) – Jede gültige DuckDB-SQL-Anweisung

  • Ausgabe : Abfrageergebnisse als Text (oder Erfolgsmeldung für Vorgänge wie CREATE/INSERT)

[!NOTE] Der Server bietet eine einzige einheitliche query anstelle separater spezialisierter Funktionen, da moderne LLMs für jeden Datenbankvorgang (SELECT, CREATE TABLE, JOIN usw.) geeignetes SQL generieren können, ohne dass separate Endpunkte erforderlich sind.

[!NOTE] Wenn der Server im readonly Modus ausgeführt wird, wird der native Schreibschutz von DuckDB erzwungen. Dadurch wird sichergestellt, dass das Sprachmodell (LLM) keine Schreibvorgänge (CREATE, INSERT, UPDATE, DELETE) ausführen kann. Dadurch wird die Datenintegrität gewahrt und unbeabsichtigte Änderungen werden verhindert.

Konfiguration

Erforderliche Parameter

• db-path (Zeichenfolge): Pfad zur DuckDB-Datenbankdatei

  • Der Server erstellt automatisch die Datenbankdatei und die übergeordneten Verzeichnisse, falls diese nicht vorhanden sind

  • Wenn --readonly angegeben ist und die Datenbankdatei nicht existiert, schlägt der Serverstart mit einem Fehler fehl

Optionale Parameter

• --readonly : Server im schreibgeschützten Modus ausführen (Standard: false )

  • Beschreibung : Wenn dieses Flag gesetzt ist, arbeitet der Server im Nur-Lese-Modus. Das bedeutet:

    • Die DuckDB-Datenbank wird mit read_only=True geöffnet, wodurch Schreibvorgänge verhindert werden.

    • Wenn die angegebene Datenbankdatei nicht existiert, wird sie nicht erstellt.

    • Sicherheitsvorteil : Verhindert, dass das Sprachmodell (LLM) Schreibvorgänge durchführt, und stellt sicher, dass die Datenbank unverändert bleibt.

  • Referenz : Weitere Einzelheiten zu schreibgeschützten Verbindungen in DuckDB finden Sie in der DuckDB Python API-Dokumentation .

• --keep-connection : Verwendet einen einzelnen DuckDB-Verbindungsmodus erneut (Standard: false )

  • Beschreibung : Wenn dieses Flag gesetzt ist, wird eine einzelne DuckDB-Verbindung für die gesamte Serverlebensdauer wiederverwendet. Aktiviert temporäre Objekte und etwas schnellere Abfragen, kann aber eine exklusive Sperre für die Datei halten.

Installation

Installation über Smithery

So installieren Sie DuckDB Server für Claude Desktop automatisch über Smithery :

npx -y @smithery/cli install mcp-server-duckdb --client claude

Claude Desktop Integration

Konfigurieren Sie den MCP-Server in der Konfigurationsdatei von Claude Desktop:

macOS

Speicherort: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows

Speicherort: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "duckdb": {
      "command": "uvx",
      "args": [
        "mcp-server-duckdb",
        "--db-path",
        "~/mcp-server-duckdb/data/data.db"
      ]
    }
  }
}

• Hinweis: ~/mcp-server-duckdb/data/data.db sollte durch den tatsächlichen Pfad zur DuckDB-Datenbankdatei ersetzt werden.

Entwicklung

Voraussetzungen

• Python mit uv -Paketmanager

• DuckDB Python-Paket

• MCP-Serverabhängigkeiten

Debuggen

Das Debuggen von MCP-Servern kann aufgrund ihrer stdio-basierten Kommunikation eine Herausforderung darstellen. Für optimales Debugging empfehlen wir die Verwendung des MCP Inspector .

Verwenden des MCP Inspector

1. Installieren Sie den Inspector mit npm:

npx @modelcontextprotocol/inspector uv --directory ~/codes/mcp-server-duckdb run mcp-server-duckdb --db-path ~/mcp-server-duckdb/data/data.db

2. Öffnen Sie die angegebene URL in Ihrem Browser, um auf die Debugging-Oberfläche zuzugreifen

Der Inspektor bietet Einblick in:

• Anfrage-/Antwort-Kommunikation

• Werkzeugausführung

• Serverstatus

• Fehlermeldungen