MotherDuckのDuckDB MCPサーバー
DuckDB および MotherDuck データベースと対話し、AI アシスタントおよび IDE に SQL 分析機能を提供する MCP サーバー実装。
リソース
特徴
- ハイブリッド実行: ローカルの DuckDB またはクラウドベースの MotherDuck データベースからデータをクエリします
- クラウドストレージ統合: MotherDuckの統合により、Amazon S3やその他のクラウドストレージに保存されたデータにアクセスできます。
- データ共有: データベースを作成して共有する
- SQL 分析: DuckDB の SQL 方言を使用して、AI アシスタントまたは IDE から任意のサイズのデータを直接クエリします。
- サーバーレスアーキテクチャ: インスタンスやクラスターを構成することなく分析を実行
コンポーネント
プロンプト
サーバーは 1 つのプロンプトを提供します:
duckdb-motherduck-initial-prompt : DuckDB または MotherDuck への接続を初期化し、操作を開始するためのプロンプト
ツール
サーバーは次の 1 つのツールを提供します。
query : DuckDBまたはMotherDuckデータベースでSQLクエリを実行する- 入力:
query (文字列、必須): 実行するSQLクエリ
DuckDB と MotherDuck の両方とのすべてのやり取りは、SQL クエリの記述を通じて行われます。
はじめる
一般的な前提条件
uvがインストールされている場合は、 pip install uvまたはbrew install uvを使用してインストールできます。
MCP を Claude Desktop またはその他の MCP 互換クライアントと共に使用する予定の場合は、クライアントをインストールする必要があります。
DuckDBの前提条件
- 前提条件はありません。MCPサーバーは、オンザフライでインメモリデータベースを作成できます。
- または、既存のローカル DuckDB データベース ファイル、またはリモート オブジェクト ストレージ (AWS S3 など) に保存されているファイルに接続します。
ローカル DuckDB への接続を参照してください。
MotherDuckの前提条件
カーソルとの使用
- まだインストールしていない場合は、 cursor.com/downloadsからCursorをインストールしてください。
- オープンカーソル:
- 初めてグローバルに設定するには、[設定] -> [MCP] に移動し、[+ 新しいグローバル MCP サーバーを追加] をクリックします。
- これにより、
mcp.jsonファイルが開き、次の構成が追加されます。
{
"mcpServers": {
"mcp-server-motherduck": {
"command": "uvx",
"args": [
"mcp-server-motherduck",
"--db-path",
"md:",
"--motherduck-token",
"<YOUR_MOTHERDUCK_TOKEN_HERE>"
]
}
}
}
VS Codeでの使用
- 最も速いインストールを行うには、この README の上部にある「UV でインストール」ボタンのいずれかをクリックします。
手動インストール
VS Codeのユーザー設定（JSON）ファイルに、以下のJSONブロックを追加します。Ctrl Ctrl + Shift + Pを押してPreferences: Open User Settings (JSON)と入力することで実行できます。
{
"mcp": {
"inputs": [
{
"type": "promptString",
"id": "motherduck_token",
"description": "MotherDuck Token",
"password": true
}
],
"servers": {
"motherduck": {
"command": "uvx",
"args": [
"mcp-server-motherduck",
"--db-path",
"md:",
"--motherduck-token",
"${input:motherduck_token}"
]
}
}
}
}
オプションとして、ワークスペース内の.vscode/mcp.jsonというファイルに追加することもできます。これにより、他のユーザーと設定を共有できるようになります。
{
"inputs": [
{
"type": "promptString",
"id": "motherduck_token",
"description": "MotherDuck Token",
"password": true
}
],
"servers": {
"motherduck": {
"command": "uvx",
"args": [
"mcp-server-motherduck",
"--db-path",
"md:",
"--motherduck-token",
"${input:motherduck_token}"
]
}
}
}
Claude Desktopでの使用
- まだインストールしていない場合は、 claude.ai/ download から Claude Desktop をインストールしてください。
- Claude Desktop 構成ファイルを開きます。
- すぐにアクセスしたり、初めて作成したりするには、Claude デスクトップ アプリを開き、[設定] を選択して [開発者] タブをクリックし、最後に [構成の編集] ボタンをクリックします。
claude_desktop_config.jsonに次の構成を追加します。
{
"mcpServers": {
"mcp-server-motherduck": {
"command": "uvx",
"args": [
"mcp-server-motherduck",
"--db-path",
"md:",
"--motherduck-token",
"<YOUR_MOTHERDUCK_TOKEN_HERE>"
]
}
}
}
重要な注意事項:
YOUR_MOTHERDUCK_TOKEN_HEREを実際のMotherDuckトークンに置き換えます。YOUR_HOME_FOLDER_PATHホームディレクトリへのパスに置き換えます（DuckDBのファイル操作に必要です）。例えばmacOSでは、 /Users/your_usernameとなります。- DuckDB が正しく機能するには、
HOME環境変数が必要です。
MotherDuck にクエリを実行する際の MCP サーバーのセキュリティ保護
MCP サーバーがサードパーティに公開されており、データへの読み取りアクセスのみを許可する必要がある場合は、読み取りスケーリング トークンを使用し、MCP サーバーを SaaS モードで実行することをお勧めします。
**読み取りスケーリングトークンは、**最大4つの同時読み取りレプリカを許可することでスケーラブルな読み取り操作を可能にする特別なアクセストークンです。これにより、書き込み機能を制限しながら複数のエンドユーザーのパフォーマンスが向上します。読み取りスケーリングトークンの作成方法については、 読み取りスケーリングのドキュメントを参照してください。
MotherDuckのSaaSモードは、ローカルファイル、データベース、拡張機能、設定へのアクセスを制限することでセキュリティを強化します。より厳格な環境保護が必要なサードパーティ製ツールに最適です。詳細については、 SaaSモードのドキュメントをご覧ください。
安全な構成
{
"mcpServers": {
"mcp-server-motherduck": {
"command": "uvx",
"args": [
"mcp-server-motherduck",
"--db-path",
"md:",
"--motherduck-token",
"<YOUR_READ_SCALING_TOKEN_HERE>",
"--saas-mode"
]
}
}
}
ローカルDuckDBに接続する
ローカル DuckDB に接続するには、MotherDuck トークンを使用する代わりに、ローカル DuckDB データベース ファイルへのパスを指定するか、メモリ内データベースの場合は:memory:使用します。
インメモリデータベース:
{
"mcpServers": {
"mcp-server-motherduck": {
"command": "uvx",
"args": [
"mcp-server-motherduck",
"--db-path",
":memory:"
]
}
}
}
ローカル DuckDB ファイル:
{
"mcpServers": {
"mcp-server-motherduck": {
"command": "uvx",
"args": [
"mcp-server-motherduck",
"--db-path",
"/path/to/your/local.db"
]
}
}
}
読み取り専用モードのローカルDuckDBファイル:
{
"mcpServers": {
"mcp-server-motherduck": {
"command": "uvx",
"args": [
"mcp-server-motherduck",
"--db-path",
"/path/to/your/local.db",
"--read-only"
]
}
}
}
注：ローカルファイルベースのDuckDB接続の読み取り専用モードでは、短命接続も使用されます。クエリMCPツールが使用されるたびに、一時的な読み取り専用接続が作成され、クエリが実行され、接続が閉じられます。この機能は、 DBTを使用してDuckDB内でデータをモデリングし、MCPクライアント（Windsurf/Cline/Claude/Cursor）を使用してデータベースを探索するというワークフローから着想を得ました。短命接続により、各ツールは実行後に接続を解放し、次のツールが接続できるようになります。
クエリの例
設定が完了すると、たとえば Claude に次のようなクエリを実行するよう依頼できるようになります。
- 「MotherDuckで新しいデータベースとテーブルを作成する」
- 「ローカルCSVファイルからデータをクエリする」
- 「ローカルの DuckDB データベースのデータを MotherDuck のテーブルに結合する」
- 「Amazon S3 に保存されたデータを分析する」
テスト
サーバーはClaude DesktopやCursorなどのツールで実行できるように設計されていますが、テスト目的で手動で起動することもできます。手動でサーバーをテストする場合は、 --db-pathパラメータを使用して接続するデータベースを指定できます。
- デフォルトのMotherDuckデータベース:
- デフォルトの MotherDuck データベースに接続するには、
--motherduck-tokenパラメータを使用して認証トークンを渡す必要があります。
uvx mcp-server-motherduck --db-path md: --motherduck-token <your_motherduck_token>
- 特定のMotherDuckデータベース:
uvx mcp-server-motherduck --db-path md:your_database_name --motherduck-token <your_motherduck_token>
- ローカルDuckDBデータベース:
uvx mcp-server-motherduck --db-path /path/to/your/local.db
- インメモリデータベース:
uvx mcp-server-motherduck --db-path :memory:
データベース パスを指定せずにmotherduck_token環境変数を設定した場合、サーバーは自動的にデフォルトの MotherDuck データベース ( md: :) に接続します。
SSEモードで実行
次のコマンドを実行すると、サーバーはsupergatewayを使用して SSE モードを実行することもできます。
npx -y supergateway --stdio "uvx mcp-server-motherduck --db-path md: --motherduck-token <your_motherduck_token>"
また、Claude Desktop、Cursor などのクライアントをこのエンドポイントにポイントすることもできます。
開発構成
ローカル開発環境からサーバーを実行するには、次の構成を使用します。
{
"mcpServers": {
"mcp-server-motherduck": {
"command": "uv",
"args": [
"--directory",
"/path/to/your/local/mcp-server-motherduck",
"run",
"mcp-server-motherduck",
"--db-path",
"md:",
"--motherduck-token",
"<YOUR_MOTHERDUCK_TOKEN_HERE>"
]
}
}
}
トラブルシューティング
- 接続の問題が発生した場合は、MotherDuckトークンが正しいことを確認してください
- ローカルファイルアクセスの問題の場合は、
--home-dirパラメータが正しく設定されていることを確認してください。 uvxコマンドがPATHで使用可能であることを確認してくださいspawn uvx ENOENTエラーが発生した場合は、 uvxへのフルパス（ which uvxの出力）を指定してみてください。- 以前のバージョンv0.4.0では環境変数を使用していましたが、現在はパラメータを使用しています。
ライセンス
このMCPサーバーはMITライセンスに基づいてライセンスされています。つまり、MITライセンスの条件に従って、ソフトウェアを自由に使用、改変、配布することができます。詳細については、プロジェクトリポジトリのLICENSEファイルをご覧ください。