星战科技xingzhan.cloud
返回市场
麦普服务器母鸭

麦普服务器母鸭

作者：motherduckdb367 星标更新：2025-11-11
安装使用来源：spider==github.com

项目介绍

技术文档摘要

MotherDuck 的 DuckDB MCP 服务器

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

<img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="在 Cursor 中安装">

资源

特性

  • 混合执行：从本地 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 查询完成的。

结果限制：查询结果会自动限制以防止占用过多上下文：

  • 默认最大 1024 行（可通过 --max-rows 配置）
  • 默认最大 50,000 字符（可通过 --max-chars 配置）
  • 截断响应包含有关截断的通知

命令行参数

MCP 服务器支持以下参数：

参数类型默认值描述
--transport选择stdio传输类型。选项：stdio，sse，stream
--port整数8000监听 sse 和流传输模式的端口
--host字符串127.0.0.1绑定 MCP 服务器的主机（用于 sse 和流传输模式）
--db-path字符串md:本地 DuckDB 数据库文件路径、MotherDuck 数据库或 S3 URL（例如，s3://bucket/path/to/db.duckdb）
--motherduck-token字符串None连接到 MotherDuck 数据库时使用的访问令牌（默认使用 motherduck_token 环境变量）
--read-only标志False以只读模式连接到 DuckDB 或 MotherD.uck 的标志。对于 DuckDB，它使用短暂连接以启用并发访问
--home-dir字符串NoneDuckDB 的主目录（默认使用 HOME 环境变量）
--saas-mode标志False以 SaaS 模式 连接到 MotherDuck 的标志（禁用本地 DuckDB 的文件系统和写权限）
--json-response标志False启用 HTTP 流的 JSON 响应。仅支持 stream 传输
--max-rows整数1024查询返回的最大行数。
--max-chars整数50000查询结果中的最大字符数。
--query-timeout整数-1查询执行超时时间（秒）。设置为 -1 取消超时（默认）。

快速使用示例

# 以只读模式连接到本地 DuckDB 文件
uvx mcp-server-motherduck --db-path /path/to/local.db --read-only

# 使用令牌连接到 MotherDuck
uvx mcp-server-motherduck --db-path md: --motherduck-token YOUR_TOKEN

# 以只读模式连接到本地 DuckDB 文件
uvx mcp-server-motherduck --db-path /path/to/local.db --read-only

# 在 SaaS 模式下连接到 MotherDuck，增强安全性并使用流传输模式
uvx mcp-server-motherduck --transport stream --db-path md: --motherduck-token YOUR_TOKEN --saas-mode

# 自定义结果截断限制
uvx mcp-server-motherduck --db-path md: --motherduck-token YOUR_TOKEN --max-rows 2048 --max-chars 100000

# 启用查询超时（5 分钟）
uvx mcp-server-motherduck --db-path md: --motherduck-token YOUR_TOKEN --query-timeout 300

开始使用

通用前提条件

  • 安装了 uv，可以使用 pip install uv 或 brew install uv 安装

如果您计划使用 Claude Desktop 或任何其他兼容 MCP 的客户端，则需要安装客户端。

DuckDB 的前提条件

  • 无需前提条件。MCP 服务器可以在运行时创建内存数据库
  • 或者连接到现有的本地 DuckDB 数据库文件，或者存储在远程对象存储上的数据库文件（例如，AWS S3）。

参见 连接到本地 DuckDB。

MotherDuck 的前提条件

与 Cursor 的使用

  1. 如果尚未安装，请从 cursor.com/downloads 安装 Cursor

  2. 打开 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 的使用

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

为了快速安装，请点击顶部的“使用 UV 安装”按钮之一。

手动安装

在 VS Code 的用户设置（JSON）文件中添加以下 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.ai/download 安装 Claude Desktop

  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 令牌

与 Claude Code 的使用

Claude Code 通过 CLI 命令或 JSON 配置支持 MCP 服务器。以下是两种设置方法：

方法 1：使用 CLI 命令

直接使用 Claude Code CLI 添加 MotherDuck MCP 服务器：

claude mcp add mcp-server-motherduck uvx mcp-server-motherduck -- --db-path md: --motherduck-token <YOUR_MOTHERDUCK_TOKEN_HERE>

方法 2：使用 JSON 配置

使用 JSON 配置添加服务器：

claude mcp add-json mcp-server-motherduck '{
  "command": "uvx",
  "args": [
    "mcp-server-motherduck",
    "--db-path",
    "md:",
    "--motherduck-token",
    "<YOUR_MOTHERDUCK_TOKEN_HERE>"
  ]
}'

作用域选项：

  • 使用 --local（默认）进行项目特定配置
  • 使用 --project 通过 .mcp.json 与团队共享配置
  • 使用 --user 让服务器在所有项目中可用

重要说明：

  • 将 YOUR_MOTHERDUCK_TOKEN_HERE 替换为您实际的 MotherDuck 令牌
  • Claude Code 还支持环境变量扩展，因此如果您设置了环境变量，可以使用 ${MOTHERDUCK_TOKEN}

当查询 MotherDuck 时保护您的 MCP 服务器

如果 MCP 服务器暴露给第三方并且只能访问数据的读取权限，我们建议使用读取缩放令牌并以 SaaS 模式运行 MCP 服务器。

读取缩放令牌 是特殊的访问令牌，通过允许最多 4 个并发读取副本，使可扩展的读取操作成为可能，从而提高多个最终用户的性能，同时限制写入能力。 参阅 读取缩放文档，了解如何创建读取缩放令牌。

SaaS 模式 在 MotherDuck 中增强了安全性，通过限制其对本地文件、数据库、扩展和配置的访问，使其非常适合需要更严格环境保护的第三方工具。了解更多关于它的内容，请参阅 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）来探索数据库。短暂连接允许每个工具运行并释放其连接，以便下一个工具能够连接。

连接到 S3 上的 DuckDB

您可以提供 S3 URL 作为数据库路径来连接到存储在 Amazon S3 上的 DuckDB 数据库。服务器将自动从您的环境变量中配置必要的 S3 凭据。

{
  "mcpServers": {
    "mcp-server-motherduck": {
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--db-path",
        "s3://your-bucket/path/to/database.duckdb"
      ],
      "env": {
        "AWS_ACCESS_KEY_ID": "<your_key>",
        "AWS_SECRET_ACCESS_KEY": "<your_secret>",
        "AWS_DEFAULT_REGION": "<your_region>"
      }
    }
  }
}

注意：对于 S3 连接：

  • AWS 凭证必须通过环境变量（AWS_ACCESS_KEY_ID，AWS_SECRET_ACCESS_KEY，可选 AWS_DEFAULT_REGION）提供
  • 对于临时凭证（AWS SSO），设置 AWS_SESSION_TOKEN 环境变量（可选 AWS_DEFAULT_REGION）以自动使用 DuckDB 的 credential_chain 提供者。
  • S3 数据