使用说明

项目简介

mcp-server-motherduck 是一个基于 Model Context Protocol (MCP) 的服务器实现，它充当 LLM 客户端和 MotherDuck / DuckDB 数据库之间的桥梁。通过此 MCP 服务器，LLM 能够以安全、标准化的方式查询和操作 DuckDB 或 MotherDuck 数据库。

主要功能点

连接管理: 支持连接到 MotherDuck 云数据库和本地 DuckDB 数据库。
SQL 查询工具: 提供 'query' 工具，允许 LLM 客户端执行 DuckDB SQL 查询并获取结果。
Prompt 模板: 内置 'duckdb-motherduck-prompt' 模板，引导用户初始化数据库连接和开始数据交互。
标准化 MCP 协议: 遵循 MCP 协议标准，易于集成到任何支持 MCP 协议的 LLM 客户端，例如 Claude Desktop。

安装步骤

环境准备: 确保你的系统已安装 Python 环境。

下载仓库: 从 GitHub 克隆或下载 'mcp-server-motherduck' 仓库到本地。

git clone https://github.com/motherduckdb/mcp-server-motherduck.git
cd mcp-server-motherduck

安装依赖: 使用 pip 安装项目依赖。
```
pip install .
```

服务器配置

要将此 MCP 服务器配置到 MCP 客户端（例如 Claude Desktop），你需要提供服务器的启动命令和参数。以下是 Claude Desktop 配置文件 'claude_desktop_config.json' 的配置示例：

"mcpServers": {
  "mcp-server-motherduck": {
    "command": "uvx",
    "args": [
      "mcp-server-motherduck"
    ],
    "env": {
      "motherduck_token": "<your-motherduck-token>",  // 替换为你的 MotherDuck 访问令牌，如果使用 MotherDuck 的话
      "HOME": "<your-home-folder-for-project-files>" // 替换为你的项目文件所在的Home目录，DuckDB 需要此环境变量
    }
  }
}

配置参数说明:

'"mcp-server-motherduck"': 服务器名称，可以自定义。
'"command": "uvx"': 启动命令，'uvx' 是一个通用的 Python 运行器，你需要确保你的环境中可以使用 'uvx' 或将其替换为 'python -m mcp_server_motherduck'。
'"args": ["mcp-server-motherduck"]': 传递给 'uvx' 的参数，这里 'mcp-server-motherduck' 是指 'mcp_server_motherduck' 包的入口点。
'"env"': 环境变量配置：
- '"motherduck_token"': (可选) 如果需要连接 MotherDuck 数据库，请设置此环境变量为你的 MotherDuck 访问令牌。你可以在 MotherDuck 官方文档中找到获取令牌的方法。如果只使用本地 DuckDB，则不需要设置此项。
- '"HOME"': (必须) DuckDB 需要 'HOME' 环境变量来定位用户目录，请将其设置为你的项目文件所在的 Home 目录。

注意: 请根据你的实际 Python 环境和是否使用 MotherDuck 数据库来调整配置。

基本使用方法

启动 MCP 服务器: 当你在 MCP 客户端（如 Claude Desktop）中配置并启用 'mcp-server-motherduck' 后，服务器会在后台自动启动。
与 LLM 交互: 在 LLM 客户端中，你可以指示 LLM 使用 'duckdb-motherduck-prompt' 来初始化与数据库的连接。
使用 'query' 工具: 当需要执行 SQL 查询时，指示 LLM 调用名为 'query' 的工具，并提供要执行的 SQL 查询语句作为参数。
查看结果: LLM 客户端会接收并展示 'query' 工具返回的数据库查询结果。

示例对话流程 (在 Claude Desktop 或其他 MCP 客户端中):

用户: "我想查询我的数据库。"

LLM: (使用 'duckdb-motherduck-prompt' 初始化连接) "您好！请问您想在 MotherDuck 还是本地 DuckDB 数据库上运行查询？"

用户: "我想查询 MotherDuck 数据库，查一下 sales 表的数据。"

LLM: (调用 'query' 工具，执行 'SELECT * FROM sales LIMIT 10;' 查询) "好的，这是 sales 表的前 10 条数据：\n[查询结果显示在这里]"

通过以上步骤，你就可以利用 mcp-server-motherduck MCP 服务器，在 LLM 应用中无缝集成 MotherDuck 和 DuckDB 数据库的强大数据查询能力。

关键词