MotherDuck MCP Server

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 が必要です。

クイックスタート

前提条件: uv を pip install uv または brew install 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 セキュリティガイド を参照してください。

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

環境変数

トラブルシューティング

• 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