MotherDuck MCP 服务器

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

特性

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

组件

提示词 (Prompts)

服务器提供一个提示词：

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

工具 (Tools)

服务器提供一个工具：

• query: 在 MotherDuck/DuckDB 数据库上执行 SQL 查询
  • 输入 (Inputs):
    • 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. 安全地存储该令牌，以便在配置中使用

在 VS Code 中使用

1. 为了最快的安装，请单击此 README 顶部的“使用 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 中使用

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
• DuckDB 需要 HOME 环境变量才能正常运行。

示例查询

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

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

测试

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

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 文件。