MotherDuck's DuckDB MCP Server

DuckDB / MotherDuck ローカル MCP サーバー

AI アシスタントや IDE 向けの SQL 分析とデータエンジニアリング。

DuckDB の強力な分析用 SQL エンジンを使って、AI アシスタントをデータに接続できます。ローカルの DuckDB ファイル、インメモリデータベース、S3 ホストのデータベース、MotherDuck への接続に対応しています。SQL の読み取り・書き込みクエリの実行、データベースカタログの閲覧、複数のデータベース接続のオンデマンド切り替えが可能です。

MotherDuck 用のフルマネージドなリモート MCP サーバーをお探しですか？ → MotherDuck リモート MCP のドキュメントへ

リモート MCP とローカル MCP

クイックスタート

前提条件：pip install uv または brew install uv で uv をインストールしてください。

インメモリ DuckDB への接続（開発モード）

{
  "mcpServers": {
    "DuckDB (in-memory, r/w)": {
      "command": "uvx",
      "args": ["mcp-server-motherduck", "--db-path", ":memory:", "--read-write", "--allow-switch-databases"]
    }
  }
}

ガードレールのない柔軟な環境で、読み書きアクセスと、実行時に任意のデータベース（ローカルファイル、S3、MotherDuck）へ切り替える機能を利用できます。

読み取り専用モードでローカルの DuckDB ファイルに接続

{
  "mcpServers": {
    "DuckDB (read-only)": {
      "command": "uvx",
      "args": ["mcp-server-motherduck", "--db-path", "/absolute/path/to/your.duckdb"]
    }
  }
}

指定した DuckDB ファイルに読み取り専用モードで接続します。ファイルロックを保持しないため、同じ DuckDB ファイルへの書き込み接続と併用するのに便利です。s3://bucket/path.duckdb を使用して、S3 上のリモート DuckDB ファイルにも接続できます。S3 認証については、環境変数をご覧ください。MCP へのサードパーティーアクセスを検討している場合は、本番環境向けのセキュリティ対策をご覧ください。

読み書きモードで MotherDuck に接続

{
  "mcpServers": {
    "MotherDuck (local, r/w)": {
      "command": "uvx",
      "args": ["mcp-server-motherduck", "--db-path", "md:", "--read-write"],
      "env": {
        "motherduck_token": "<YOUR_MOTHERDUCK_TOKEN>"
      }
    }
  }
}

その他のオプションについてはコマンドラインパラメーターを、本番環境へのデプロイに関するガイダンスについては本番環境向けのセキュリティ対策を、問題が発生した場合はトラブルシューティングをご覧ください。

クライアントのセットアップ

クライアント	設定場所	ワンクリックインストール
Claude Desktop	Settings → Developer → Edit Config	.mcpb (MCP Bundle)
Claude Code	以下の CLI コマンドを使用	-
Codex CLI	以下の CLI コマンド、または ~/.codex/config.toml を使用	-
Gemini CLI	以下の CLI コマンド、または ~/.gemini/settings.json を使用	-
Cursor	Settings → MCP → Add new global MCP server
VS Code	Ctrl+Shift+P → "Preferences: Open User Settings (JSON)"
Kiro	~/.kiro/settings/mcp.json（グローバル）または .kiro/settings/mcp.json（プロジェクト）

MCP 互換のクライアントであれば、このサーバーを使用できます。クイックスタートの JSON 設定を、クライアントの MCP 設定ファイルに追加してください。設定ファイルの場所については、クライアントのドキュメントを参照してください。

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>"
      }
    }
  }
}

ツール

*--allow-switch-databases フラグが必要です

すべてのツールは JSON を返します。結果はデフォルトで 1024 行／50,000 文字に制限されています（--max-rows、--max-chars で設定可能です）。

本番環境のセキュリティ対策

セルフホスト型 MCP サーバーへのアクセスを第三者に許可する場合、読み取り専用モードだけでは不十分です。ローカルファイルシステムへのアクセス、DuckDB 設定の変更、その他の機密情報に関わる可能性のある操作は引き続き可能です。

第三者がアクセスする本番環境のデプロイでは、MotherDuck Remote MCP をおすすめします。セットアップ不要で、読み書きに対応し、MotherDuck がホストします。

MotherDuck MCP をセルフホストする場合： このリポジトリをフォークし、必要に応じてカスタマイズしてください。サービスアカウント に 読み取りスケーリングトークン を使用し、ローカルファイルへのアクセスを制限するために SaaS モード を有効にしてください。

DuckDB MCP をセルフホストする場合： --init-sql を使用してセキュリティ設定を適用してください。利用可能なオプションについては、DuckDB のセキュリティ対策ガイドをご覧ください。

Docker

Streamable HTTP をポート 8000 で使用してサーバーをビルド、実行します（デフォルトではインメモリ DuckDB を使用します）。

docker build -t mcp-server-motherduck .
docker run --rm -p 8000:8000 mcp-server-motherduck

トークンを渡してコマンドを上書きすると、MotherDuck に接続できます。

docker run --rm -p 8000:8000 \
  -e motherduck_token="$MOTHERDUCK_TOKEN" \
  mcp-server-motherduck --transport http --db-path md:

MCP エンドポイントは http://localhost:8000/mcp で利用できます。以下の CLI フラグと環境変数も引き続き適用されます。

コマンドラインパラメーター

環境変数

トラブルシューティング

• spawn uvx ENOENT：uvx のフルパスを指定してください（which uvx を実行すると確認できます）
• ファイルがロックされている：--ephemeral-connections が有効になっていること（デフォルト：true）、また読み書きモードで接続していないことを確認してください

リソース

• MotherDuck MCP のドキュメント
• ループを閉じる：MCP、DuckDB、AI でデータパイプラインを高速化（ブログ）
• MCP と DuckDB でデータパイプラインを高速化（YouTube）

開発

ソースから実行するには：

{
  "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>"
      }
    }
  }
}

リリースプロセス

1. Release New Version GitHub アクションを実行します
2. MAJOR.MINOR.PATCH 形式でバージョンを入力します
3. ワークフローによってバージョンが更新され、PyPI／MCP レジストリに公開された後、MCPB パッケージを含む GitHub リリースが作成されます

ライセンス

MIT ライセンスです。詳細は LICENSE ファイルをご覧ください。

mcp-name: io.github.motherduckdb/mcp-server-motherduck