MotherDuck

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

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

DuckDB の強力な分析 SQL エンジンを使用して、AI アシスタントをデータに接続します。ローカルの DuckDB ファイル、インメモリデータベース、S3 でホストされたデータベース、MotherDuck への接続をサポートします。SQL の読み取り/書き込みクエリの実行、データベースカタログの参照、異なるデータベース接続間のオンザフライでの切り替えが可能です。

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

リモート MCP とローカル MCP

📝 v0.x から移行しますか？

• デフォルトで読み取り専用: サーバーはデフォルトで読み取り専用モードで実行されるようになりました。書き込みアクセスを有効にするには --read-write を追加してください。本番環境向けのセキュリティ を参照してください。
• デフォルトデータベースの変更: --db-path のデフォルトが md: から :memory: に変更されました。MotherDuck を明示的に指定するには --db-path md: を追加してください。
• MotherDuck の読み取り専用には読み取りスケーリングトークンが必要です: 読み取り専用モードでの MotherDuck 接続には 読み取りスケーリングトークン が必要です。通常のトークンには --read-write が必要です。

クイックスタート

前提条件: 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	設定 → 開発者 → 設定を編集	.mcpb (MCP バンドル)
Claude Code	以下の CLI コマンドを使用	-
Codex CLI	以下の CLI コマンドまたは ~/.codex/config.toml を使用	-
Gemini CLI	以下の CLI コマンドまたは ~/.gemini/settings.json を使用	-
Cursor	設定 → MCP → 新しいグローバル MCP サーバーを追加
VS Code	Ctrl+Shift+P → "基本設定: ユーザー設定を開く (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 リモート MCP をお勧めします — ゼロセットアップ、読み取り/書き込み対応、MotherDuck がホストします。

MotherDuck MCP のセルフホスティング: このリポジトリをフォークし、必要に応じてカスタマイズします。サービスアカウント と 読み取りスケーリングトークン を使用し、SaaS モード を有効にしてローカルファイルアクセスを制限します。

DuckDB MCP のセルフホスティング: --init-sql を使用してセキュリティ設定を適用します。利用可能なオプションについては、DuckDB セキュリティガイド を参照してください。

Docker

ポート 8000 で Streamable HTTP を使用してサーバーをビルドして実行します (デフォルトはインメモリ 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 Action を実行します
2. MAJOR.MINOR.PATCH 形式でバージョンを入力します
3. ワークフローがバージョンを上げ、PyPI/MCP レジストリに公開し、MCPB パッケージを含む GitHub リリースを作成します

ライセンス

MIT ライセンス - LICENSE ファイルを参照してください。

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