mcp-server-duckdb

mcp-server-duckdb

DuckDB 向けの Model Context Protocol（MCP）サーバー実装で、MCP ツールを通じてデータベースを操作できます。 LLM に分析させると興味深いでしょう。DuckDB はローカルでの分析に適しています。

概要

このサーバーを使用すると、Model Context Protocol を通じて DuckDB データベースを操作でき、クエリの実行、テーブルの作成、スキーマの確認などのデータベース操作が可能になります。

コンポーネント

リソース

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

プロンプト

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

ツール

このサーバーは、次のデータベース操作ツールを実装しています。

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

メモ

最新の LLM は、個別のエンドポイントがなくても、あらゆるデータベース操作（SELECT、CREATE TABLE、JOIN など）に適切な SQL を生成できるため、このサーバーでは用途別の関数を個別に用意せず、単一の統合された query 関数を提供しています。

メモ

サーバーが readonly モードで実行されている場合、DuckDB のネイティブな読み取り専用保護が適用されます。 これにより、言語モデル（LLM）による書き込み操作（CREATE、INSERT、UPDATE、DELETE）が禁止され、データの完全性が保たれ、意図しない変更を防止できます。

設定

必須パラメーター

• db-path（文字列）：DuckDB データベースファイルへのパス
  • データベースファイルや親ディレクトリが存在しない場合、サーバーが自動的に作成します
  • --readonly が指定されていて、データベースファイルが存在しない場合、エラーが発生してサーバーの起動に失敗します

オプションのパラメーター

• --readonly：サーバーを読み取り専用モードで実行します（デフォルト：false）
  • 説明：このフラグを設定すると、サーバーは読み取り専用モードで動作します。具体的には、次のとおりです。
    • DuckDB データベースは read_only=True で開かれ、あらゆる書き込み操作が禁止されます。
    • 指定したデータベースファイルが存在しない場合、作成されません。
    • セキュリティ上のメリット：言語モデル（LLM）による書き込み操作を防止し、データベースが変更されないようにします。
  • 参考資料：DuckDB の読み取り専用接続について詳しくは、DuckDB Python API documentationを参照してください。
• --keep-connection：単一の DuckDB 接続を再利用するモードです（デフォルト：false）
  • 説明：このフラグを設定すると、サーバーの稼働中、単一の DuckDB 接続を再利用します。TEMP オブジェクトを使用でき、クエリが若干高速になりますが、ファイルに排他ロックがかかる場合があります。

インストール

Smithery 経由でのインストール

Smitheryを通じて、Claude Desktop 用の DuckDB Server を自動的にインストールするには、次のコマンドを実行します。

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

Claude Desktop との連携

Claude Desktop の設定ファイルで MCP サーバーを設定します。

MacOS

場所：~/Library/Application Support/Claude/claude_desktop_config.json

Windows

場所：%APPDATA%/Claude/claude_desktop_config.json

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

• 注：~/mcp-server-duckdb/data/data.db は、DuckDB データベースファイルの実際のパスに置き換えてください。

開発

前提条件

• uv パッケージマネージャーを備えた Python
• DuckDB Python パッケージ
• MCP サーバーの依存関係

デバッグ

MCP サーバーは stdio ベースで通信するため、デバッグが難しい場合があります。快適にデバッグするには、MCP Inspector の使用をおすすめします。

MCP Inspector の使用

1. npm を使用して Inspector をインストールします。

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

2. 表示された URL をブラウザーで開き、デバッグインターフェースにアクセスします。

Inspector では、次の内容を確認できます。

• リクエスト／レスポンスの通信
• ツールの実行
• サーバーの状態
• エラーメッセージ