MotherDuck 的 DuckDB MCP 服务器

与 DuckDB 和 MotherDuck 数据库交互的 MCP 服务器实现，为 AI 助手和 IDE 提供 SQL 分析功能。

资源

Related MCP server: Duck Duck MCP

特征

混合执行：从本地 DuckDB 或/和基于云的 MotherDuck 数据库查询数据
云存储集成：借助 MotherDuck 的集成，可以访问存储在 Amazon S3 或其他云存储中的数据
数据共享：创建和共享数据库
SQL 分析：使用 DuckDB 的 SQL 方言直接从您的 AI 助手或 IDE 查询任意大小的数据
无服务器架构：无需配置实例或集群即可运行分析

成分

提示

服务器提供一个提示：

duckdb-motherduck-initial-prompt ：提示初始化与 DuckDB 或 MotherDuck 的连接并开始使用它

工具

该服务器提供了一个工具：

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 的先决条件

注册MotherDuck 账户
通过MotherDuck UI生成访问令牌
安全存储令牌以便在配置中使用

与游标一起使用

如果您还没有安装 Cursor，请从cursor.com/downloads安装
打开游标：

首次进行全局设置时，请前往“设置”->“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 一起使用

在 VS Code 中使用 UV 安装在 VS Code Insiders 中使用 UV 安装

为了最快地安装，请单击此自述文件顶部的“使用 UV 安装”按钮之一。

手动安装

将以下 JSON 块添加到 VS Code 中的“用户设置 (JSON)”文件中。您可以按下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 Desktop，请从claude.ai/download安装
打开Claude桌面配置文件：

要快速访问它或首次创建它，请打开 Claude Desktop 应用程序，选择“设置”，然后单击“开发人员”选项卡，最后单击“编辑配置”按钮。
将以下配置添加到您的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 服务器暴露给第三方并且只应具有数据读取权限，我们建议使用读取扩展令牌并以 SaaS 模式运行 MCP 服务器。

读取扩展令牌是一种特殊的访问令牌，它允许最多 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 文件。

mcp-server-motherduck