MotherDuck MCP 服务器

一个集成了 MotherDuck 和本地 DuckDB 的 MCP 服务器实现，为 Claude 提供 SQL 分析功能。

功能

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

组件

提示词

该服务器提供一个提示词：

• duckdb-motherduck-initial-prompt：用于初始化与 DuckDB 或 MotherDuck 的连接并开始工作的提示词

工具

该服务器提供一个工具：

• query：在 MotherDuck/DuckDB 数据库上执行 SQL 查询
  • 输入：
    • query (字符串，必需)：要执行的 SQL 查询

所有与 DuckDB 和 MotherDuck 的交互都是通过编写 SQL 查询来完成的。

开始使用

前提条件

• 一个 MotherDuck 账户（在 motherduck.com 注册）
• 一个 MotherDuck 访问令牌
• 安装了 uv，可以使用 pip install uv 或 brew install uv 进行安装

如果您计划将 MotherDuck MCP 与 Claude Desktop 一起使用，还需要安装 Claude Desktop。

设置您的 MotherDuck 令牌

1. 在 MotherDuck 账户 注册
2. 通过 MotherDuck UI 生成访问令牌
3. 安全地存储令牌以供配置中使用

与 Claude Desktop 一起使用

1. 如果您还没有安装 Claude Desktop，请从 claude.ai/download 下载并安装

2. 打开 Claude Desktop 配置文件：

• 要快速访问它或首次创建它，请打开 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
• HOME 环境变量对于 DuckDB 正常工作是必需的。

示例查询

配置完成后，您可以要求 Claude 运行如下查询：

• "在 MotherDuck 中创建一个新的数据库和表"
• "从我的本地 CSV 文件中查询数据"
• "将我本地的 DuckDB 数据库中的数据与 MotherDuck 中的表进行联接"
• "分析存储在 Amazon S3 中的数据"

测试

该服务器设计为由像 Claude Desktop 和 Cursor 这样的工具运行，但您可以手动启动它以进行测试。手动测试服务器时，可以使用 --db-path 参数指定要连接的数据库：

# 这里是手动测试命令示例
python server.py --db-path /path/to/your/database

1. 默认的MotherDuck数据库：

   • 要连接到默认的MotherDuck数据库，您需要使用--motherduck-token参数传递认证令牌。

   uvx mcp-server-motherduck --db-path md: --motherduck-token <your_motherduck_token>
   

2. 特定的MotherDuck数据库：

   uvx mcp-server-motherduck --db-path md:your_database_name --motherduck-token <your_motherduck_token>
   

3. 本地DuckDB数据库：

   uvx mcp-server-motherduck --db-path /path/to/your/local.db
   

4. 内存数据库：

   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指向此端点。

故障排除

• 如果遇到连接问题，请验证您的MotherDuck令牌是否正确
• 对于本地文件访问问题，请确保--home-dir参数设置正确
• 检查uvx命令是否在您的PATH中可用
• 如果遇到spawn uvx ENOENT错误，尝试指定uvx的完整路径（which uvx的输出）
• 在v0.4.0之前的版本中我们使用了环境变量，现在我们使用参数

许可证

此MCP服务器根据MIT许可证许可。这意味着您可以在遵守MIT许可证条款和条件的前提下自由使用、修改和分发该软件。更多详情，请参阅项目存储库中的LICENSE文件。