MotherDuck 的 DuckDB MCP 服务器
与 DuckDB 和 MotherDuck 数据库交互的 MCP 服务器实现，为 AI 助手和 IDE 提供 SQL 分析功能。
资源
特征
- 混合执行：从本地 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 的先决条件
与游标一起使用
- 如果您还没有安装 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 一起使用
- 为了最快地安装，请单击此自述文件顶部的“使用 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 文件。