Claude Media
DuckDB / MotherDuck MCPサーバーでローカル分析基盤に繋ぐ
Claude CodeMCPClaude連携チュートリアル

DuckDB / MotherDuck MCPサーバーでローカル分析基盤に繋ぐ

MotherDuck公式のDuckDBローカルMCPサーバーで、ファイル・S3・MotherDuckクラウドに繋ぎ、データベースを切り替えながら分析する手順をまとめます。

読了目安 約15分

サーバーを立てずに手元のファイルをそのまま分析できるのがDuckDBの持ち味です。MotherDuck公式が配布するmcp-server-motherduckは、この特性をMCP経由でClaudeに渡します。ローカルのDuckDBファイル・インメモリDB・S3上のファイル・MotherDuckクラウドのいずれにも同じサーバーで接続でき、実行中に接続先を切り替えることもできます。バージョン1系で既定の挙動が変わっているので、移行の注意点も含めて手順をまとめます。

ローカルMCPとリモートMCP、2つの選択肢

MotherDuckは同じ用途に対して2種類のMCPサーバーを用意しています。この記事で扱うのはローカル版です。

リモートMCP(MotherDuck公式ホスト)ローカルMCP(この記事)
ホスティングリモートMCP(MotherDuck公式ホスト)MotherDuckが運用ローカルMCP(この記事)自分の環境で起動
セットアップリモートMCP(MotherDuck公式ホスト)不要(ゼロセットアップ)ローカルMCP(この記事)ローカルインストールが必要
読み書きリモートMCP(MotherDuck公式ホスト)両対応ローカルMCP(この記事)両対応
ローカルファイルリモートMCP(MotherDuck公式ホスト)非対応ローカルMCP(この記事)ローカル・リモートDBを横断してファイルの入出力が可能

手元のCSVをそのまま読ませたい、ローカルファイルとS3を横断してクエリを投げたい、といった用途はローカルMCPでないと成立しません。逆にセットアップの手間を省き、MotherDuckクラウドのデータだけを扱うならリモートMCPのほうが手早く始められます。

バージョン1系で既定の挙動が変わった

もう1点、MotherDuck接続を読み取り専用モードで使う場合は、通常のトークンではなくread-scalingトークンが必要です。通常のMotherDuckトークンで読み書きしたい場合は--read-writeを付けます。

接続手順 — インメモリ・ローカルファイル・MotherDuck

前提としてuvをインストールしておきます(pip install uvまたはbrew install uv)。用途に応じて3通りの設定があります。

まず、ガードなしで試したいだけのインメモリDBです。

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

特定のローカルファイルに読み取り専用で繋ぐ場合はこちらです。ファイルロックを保持しないため、書き込み用の別接続と同時に使えます。

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

MotherDuckクラウドに読み書きで繋ぐ場合はトークンを環境変数に渡します。

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

Claude Codeではclaude mcp addで同じ設定をCLIから登録できます。

claude mcp add --scope user motherduck --transport stdio \
  --env motherduck_token=YOUR_TOKEN \
  -- uvx mcp-server-motherduck --db-path md: --read-write

Claude Desktopには.mcpb形式のワンクリックインストールも用意されています。設定画面のDeveloper → Edit Configから、上記のJSONを直接貼り付ける方法も使えます。

提供ツールとデータベースの切り替え

現行バージョンが公開するツールは5つです。

ツール機能必須入力
execute_query機能DuckDB方言でSQLクエリを実行必須入力sql
list_databases機能全データベースを一覧表示必須入力なし
list_tables機能テーブル・ビューを一覧表示必須入力なし(database/schemaで絞り込み可)
list_columns機能テーブル・ビューのカラムを一覧表示必須入力table
switch_database_connection機能接続先データベースを切り替え必須入力path

残り3つの一覧系ツールは調査の粒度で使い分けます。list_databasesは接続中のサーバーが認識しているデータベース(ローカルファイル・MotherDuckクラウド・アタッチ済みのS3ファイルなど)を横断して見せるので、「今どこに繋がっているか」を確認する起点になります。list_tablesはそこから1つのデータベースを掘り下げてテーブル・ビューの一覧を返し、database・schema引数で絞り込めるため、スキーマ数が多い環境でも目的のテーブルを探しやすくなります。list_columnsはさらに1段深く、指定したテーブル1つのカラム名と型を返す用途で、SQLを書く前にカラム名を確認したいときに使います。つまり「サーバー全体→1つのDB→1つのテーブル」という順で粒度が細かくなる3段構成です。

switch_database_connectionだけは--allow-switch-databasesフラグを付けて起動しないと使えません。このツールが有効だと、会話の途中で「今度はS3上のこのファイルを見て」と言うだけで、ローカルファイル・MotherDuck・S3のいずれにも接続を切り替えられます。逆にフラグを付けなければ、起動時に指定した1つのデータベースだけに固定され、意図しない接続先への切り替えを防げます。結果は全てJSONで返り、既定では1024行・50,000文字までに制限されます(--max-rows・--max-charsで変更可能)。

本番でサードパーティに公開する場合の注意

読み取り専用モードにしただけでは、ローカルファイルシステムへのアクセスやDuckDBの設定変更まで防げるわけではありません。社外の相手にこのMCPサーバーへのアクセスを渡す構成は、読み取り専用フラグだけでは不十分です。

第三者にアクセスを渡す本番用途では、MotherDuck自身がホストするRemote MCPが推奨されています。ゼロセットアップで読み書き両対応、運用の負担がMotherDuck側に寄ります。ローカルMCPを自前でホストし続ける場合は、サービスアカウントとread-scalingトークンを組み合わせ、SaaSモードでローカルファイルへのアクセスを制限する構成にします。DuckDB単体のファイルに対するセキュリティ設定は--init-sqlで追加できます。

トークンの選び方は用途で決まります。read-scalingトークンは読み取り専用の接続にしか使えず、書き込みを試みるとエラーになります。逆に通常のMotherDuckトークンは読み書き両方に使えるため、--read-writeを付けずに読み取り専用として使う場面でも通常トークンで動作しますが、第三者に渡す構成では書き込み権限まで含んだ通常トークンを配ること自体がリスクになります。社外の相手にサーバーを触らせるなら、Remote MCPでMotherDuck側にホスティングごと任せるか、自前ホストのままread-scalingトークンを発行したサービスアカウントに絞って権限を最小化するか、のどちらかを選ぶことになります。

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

設定ファイルのargsに渡すフラグは、用途に応じて組み合わせます。主なものは次のとおりです。

パラメータ既定値内容
--db-path既定値:memory:内容ローカルファイル(絶対パス)・md:(MotherDuck)・s3://URLのいずれか
--read-write既定値False内容書き込みアクセスを有効化
--allow-switch-databases既定値False内容switch_database_connectionツールを有効化
--max-rows既定値1024内容返す行数の上限
--max-chars既定値50000内容返す文字数の上限
--query-timeout既定値-1(無効)内容クエリタイムアウト(秒)
--init-sql既定値なし内容起動時に実行するSQL
--motherduck-saas-mode既定値False内容MotherDuck SaaSモード(ローカルアクセスを制限)
--transport既定値stdio内容stdioまたはhttp

大きな結果セットを扱うノートブック的な用途では--max-rowsと--max-charsを引き上げ、逆に応答を軽くしたい場合は絞り込みます。--query-timeoutは既定で無効なので、長時間クエリを止めたい場合は明示的に秒数を指定します。

HOME環境変数はDuckDBが拡張機能や設定の保存先を決めるのに使われ、シェル側で未設定なら--home-dirで明示的に指定します。

MotherDuckへの接続に使う--motherduck-connection-parametersは、既定でsession_hint=mcp&dbinstance_inactivity_ttl=0sが設定されています。session_hint=mcpはMotherDuck側でMCP経由の接続だと識別するためのタグで、dbinstance_inactivity_ttl=0sはアイドル状態でもインスタンスをすぐには落とさない設定です。会話が途切れがちなAIエージェント用途を前提にした既定値なので、通常は変更する必要はありません。

セキュリティ強化のために起動時SQLを流し込みたい場合は--init-sqlを使います。DuckDB自体のセキュリティ設定(Securing DuckDBガイド)と組み合わせれば、ファイルシステムへのアクセス範囲や拡張機能の読み込みを制限した状態でMCPサーバーを起動できます。

Dockerでstreamable HTTPとして起動する

stdio以外にDockerコンテナとしても配布されています。既定はインメモリDuckDBで、ポート8000でstreamable HTTPが待ち受けます。

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フラグと環境変数はそのまま適用されます。

S3上のDuckDBファイルに接続する

--db-pathにs3://bucket/path.duckdb形式のURLを渡すと、S3上のファイルにそのまま接続できます。認証はAWSの標準的な環境変数で渡します。

環境変数用途
AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY用途アクセスキーによる認証
AWS_SESSION_TOKEN用途IAMロール・SSO・EC2インスタンスプロファイルの一時credential
AWS_DEFAULT_REGION用途接続先リージョン
HOME用途DuckDBの拡張機能・設定の保存先。未設定の場合は--home-dirで明示する

よくあるつまずき

  • spawn uvx ENOENTエラーが出る: commandに指定したuvxのフルパスが解決できていない。which uvxで確認したフルパスを設定に書く
  • 書き込みができない: v1系は既定で読み取り専用。--read-writeフラグを付け忘れている
  • MotherDuckの読み取り専用接続でトークンエラーになる: 通常トークンは読み取り専用モードで使えない。read-scalingトークンに切り替えるか、--read-writeを付ける
  • ファイルがロックされて開けない: --ephemeral-connections(既定で有効)を無効化していないか、同じファイルに読み書きモードで別接続していないか確認する

よくある質問

Claude以外のクライアントでも使えますか

使えます。Claude Code・Codex CLI・Gemini CLI・Cursor・VS Code・Kiroなど、複数のMCPクライアント向けにCLIコマンドや設定例が配布元から公開されています。設定形式はクライアントごとに多少異なりますが、渡す--db-pathや--read-writeなどのフラグ自体は共通です。

複数のDuckDBファイルを同時に開けますか

switch_database_connectionは「今の接続を切り替える」ツールで、複数のデータベースを同時に開いたまま両方にクエリを投げる機能ではありません。複数ファイルを横断してJOINしたい場合は、DuckDB自体のATTACH構文をexecute_query経由で使う形になります。

まとめ

mcp-server-motherduckは、ローカルファイル・インメモリ・S3・MotherDuckクラウドを同じサーバーで扱えるのが強みです。v1系からは既定が読み取り専用に変わっているため、書き込みが必要なら--read-writeを、MotherDuckに繋ぐなら--db-path md:を明示します。switch_database_connectionを--allow-switch-databases付きで有効にしておけば、会話の途中でも分析対象を切り替えられます。社外の相手にアクセスを渡す本番運用では、読み取り専用フラグだけに頼らずMotherDuckのRemote MCPかサービスアカウント構成を検討するのが安全です。クラウドDWH側の選択肢はClaude Snowflake連携ガイド、大規模ログ集計に寄せた選択肢はClickHouse MCPサーバーにまとめています。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →