MCP Server Duckdb

🚀 mcp-server-duckdb

DuckDB用のモデルコンテキストプロトコル（MCP）サーバーで、MCPツールを通じたデータベースとの相互作用を可能にします。DuckDBはローカル分析に最適です。

🚀 クイックスタート

このサーバーは、モデルコンテキストプロトコル（MCP）を通じてDuckDBデータベースと相互作用し、クエリの実行、テーブルの作成、スキーマのチェックなどのデータベース操作を可能にします。

✨ 主な機能

リソース

現在、カスタムリソースは実装されていません。

プロンプト

現在、カスタムプロンプトは実装されていません。

ツール

このサーバーは、以下のデータベース相互作用ツールを実装しています。

• query：DuckDBデータベース上で任意のSQLクエリを実行します。
  • 入力：query（文字列） - 有効なDuckDB SQL文
  • 出力：クエリ結果をテキストとして返します（CREATE/INSERTなどの操作の場合は成功メッセージ）

⚠️ 重要な注意

このサーバーは、個別の専用機能ではなく、統一されたquery関数を提供しています。なぜなら、現代の大規模言語モデル（LLM）は、SELECT、CREATE TABLE、JOINなどの任意のデータベース操作に対して適切なSQL文を生成できるため、個別のエンドポイントを指定する必要がないからです。

⚠️ 重要な注意

サーバーが読み取り専用モードで実行される場合、DuckDBの組み込み読み取り専用保護が有効になります。 これは、言語モデル（LLM）がCREATE、INSERT、UPDATE、DELETEなどの書き込み操作を実行できないことを意味し、データの整合性を維持し、意図しない変更を防止します。

🔧 技術詳細

必要パラメータ

• db-path（文字列）：DuckDBデータベースファイルのパス
  • サーバーは、データベースファイルとその親ディレクトリが存在しない場合、自動的に作成します。
  • --readonlyを指定し、データベースファイルが存在しない場合、サーバーは起動できず、エラーが表示されます。

オプションパラメータ

• --readonly：サーバーを読み取り専用モードで実行します。
  • 説明：このフラグが設定されると、サーバーは読み取り専用モードで実行されます。これは、以下のことを意味します。
    • DuckDBデータベースはread_only=Trueで開かれ、書き込み操作が禁止されます。
    • 指定されたデータベースファイルが存在しない場合、作成されません。
    • セキュリティ上の利点：言語モデル（LLM）が書き込み操作を実行するのを防止し、データの安全性を確保します。
  • 参考：DuckDBドキュメント

📦 インストール

以下のコマンドでインストールします。

uvx add mcp-server-duckdb

Claude Desktopで統合する場合は、~/.config/claude.yamlに以下の内容を追加してください。

mcp:
  servers:
    - duckdb:
        class_path: mcp_server_duckdb.DuckDBMCPHandler

💻 使用例

基本的な使用法

Claude Desktopで使用する場合は、以下のコマンドで実行できます。

uvx serve --port 12345 duckdb:mcp-server-duckdb

その後、Claude DesktopでMCPエンドポイントをhttp://localhost:12345に設定します。

高度な使用法

以下のコマンドでデバッグサーバーを起動します。

uvx debug duckdb:mcp-server-duckdb

このデバッガーは、以下の機能を提供します。

• リクエスト/レスポンス通信の可視化
• ツール実行のトレース
• サーバー状態の監視
• エラーメッセージの表示