DuckDB MCP Server

DuckDB MCP サーバー

Model Context Protocol（MCP）サーバーです。AI アシスタントに DuckDB へのフルアクセスを提供し、プレーンな SQL を使ってローカルファイル、S3 バケット、メモリ内のデータをクエリできます。

🌟 DuckDB MCP サーバーとは？

---

できること

このサーバーは、MCP 対応のあらゆるクライアント（Claude Desktop、Cursor、VS Code など）に DuckDB を公開します。アシスタントは次の操作を実行できます。

• ローカルの CSV、Parquet、JSON ファイルに対して任意の SQL を実行する
• S3／GCS バケットを直接クエリするか、ローカルテーブルとしてキャッシュする
• スキーマを調べ、統計を算出し、可視化を提案する
• DuckDB の分析用 SQL 拡張機能（ウィンドウ関数、GROUP BY ALL、SELECT * EXCLUDE など）を使う

ツール

ツール	説明
query	任意の SQL クエリを実行します。結果は最大 10 000 行です。
analyze_schema	ファイルまたはテーブルの列と型を説明します。
analyze_data	行数、数値統計（最小値／最大値／平均値／中央値）、日付範囲、カテゴリ値の上位項目を返します。
suggest_visualizations	列の型に基づいて、グラフの種類とすぐに実行できる SQL クエリを提案します。
create_session	呼び出し間のコンテキスト追跡用に、セッションを作成またはリセットします。

リソース

次の 3 つの組み込み XML ドキュメントリソースを、アシスタントはいつでも利用できます。

リソース URI	内容
duckdb-ref://friendly-sql	DuckDB の SQL 拡張機能（GROUP BY ALL、SELECT * EXCLUDE/REPLACE、FROM 句を先に書く構文など）
duckdb-ref://data-import	CSV、Parquet、JSON、S3／GCS データの読み込み、glob パターン、複数ファイルの読み取り
duckdb-ref://visualization	時系列、棒グラフ、散布図、ヒートマップ用のグラフパターンとクエリテンプレート

---

要件

• Python 3.10+
• MCP 対応クライアント

インストール

pip install duckdb-mcp-server

ソースから：

git clone https://github.com/mustafahasankhan/duckdb-mcp-server.git
cd duckdb-mcp-server
pip install -e .

---

設定

duckdb-mcp-server --db-path <path> [options]

フラグ	必須	説明
--db-path	はい	DuckDB ファイルへのパスです。ファイルが存在しない場合は自動的に作成されます。
--readonly	いいえ	データベースを読み取り専用で開きます。ファイルが存在しない場合はエラーになります。
--s3-region	いいえ	AWS リージョンです。デフォルトでは、環境変数 AWS_DEFAULT_REGION の値を使用し、それも設定されていない場合は us-east-1 を使用します。
--s3-profile	いいえ	AWS プロファイル名です。デフォルトでは、環境変数 AWS_PROFILE の値を使用し、それも設定されていない場合は default を使用します。
--creds-from-env	いいえ	環境変数から AWS_ACCESS_KEY_ID／AWS_SECRET_ACCESS_KEY を読み込みます。

---

クライアントの設定

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）を編集します。

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

S3 アクセスを使用する場合

{
  "mcpServers": {
    "duckdb": {
      "command": "duckdb-mcp-server",
      "args": [
        "--db-path", "~/claude-duckdb/data.db",
        "--s3-region", "us-east-1",
        "--creds-from-env"
      ],
      "env": {
        "AWS_ACCESS_KEY_ID": "YOUR_KEY",
        "AWS_SECRET_ACCESS_KEY": "YOUR_SECRET"
      }
    }
  }
}

読み取り専用モード

データベースを共有している場合や、別途管理している場合に便利です。

{
  "mcpServers": {
    "duckdb": {
      "command": "duckdb-mcp-server",
      "args": ["--db-path", "/shared/analytics.db", "--readonly"]
    }
  }
}

---

会話の例

ローカルファイルのクエリ

「sales.csv を読み込んで、売上上位 5 商品を表示してください。」

SELECT
    product_name,
    SUM(quantity * price) AS revenue
FROM read_csv('sales.csv')
GROUP BY ALL
ORDER BY revenue DESC
LIMIT 5;

S3 データの操作

「今月のサインアップデータを S3 からキャッシュして、日別の内訳を表示してください。」

-- Step 1: cache the remote data locally
CREATE TABLE signups AS
  SELECT * FROM read_parquet('s3://my-bucket/signups/2026-03/*.parquet',
                             union_by_name = true);

-- Step 2: query the cached table
SELECT
    date_trunc('day', signup_at) AS day,
    COUNT(*)                     AS signups
FROM signups
GROUP BY ALL
ORDER BY day DESC;

統計分析

「orders テーブルの統計概要を教えてください。」

アシスタントは analyze_data("orders") を呼び出します。このツールは行数、列ごとの数値統計、日付範囲、カテゴリ値の上位項目を返すため、ユーザーが SQL を書く必要はありません。

---

AWS 認証情報の解決順序

1. 環境変数（--creds-from-env）：AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY
2. 名前付きプロファイル（--s3-profile）：~/.aws/credentials を読み込みます
3. 認証情報チェーン：環境変数 → 共有認証情報ファイル → インスタンスプロファイル（EC2/ECS）

---

開発

git clone https://github.com/mustafahasankhan/duckdb-mcp-server.git
cd duckdb-mcp-server

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

pytest

---

ライセンス

貢献を歓迎します！お気軽にプルリクエストを送信してください。 MIT