使用说明

项目简介

该项目 'mcp-server-duckdb' 是一个 MCP 服务器的实现，专注于为大型语言模型 (LLM) 提供与 DuckDB 数据库交互的能力。DuckDB 是一个高性能的嵌入式分析型数据库。通过此 MCP 服务器，LLM 可以使用预定义的工具来查询 DuckDB 数据库中的数据、创建新的表、并获取数据库的结构信息。这使得 LLM 能够利用 DuckDB 的数据分析能力，从而执行更复杂的数据驱动的任务。

主要功能点

数据库查询: 支持 LLM 通过 'read-query' 工具执行 SELECT 查询，从 DuckDB 数据库中检索数据。
数据写入与修改: 支持 LLM 通过 'write-query' 工具执行 INSERT, UPDATE, DELETE 查询，修改数据库中的数据 (非只读模式下)。
表结构管理: 支持 LLM 使用 'create-table' 工具创建新表 (非只读模式下)，使用 'list-tables' 工具列出数据库中所有表，使用 'describe-table' 工具获取指定表的结构信息。
只读模式: 服务器可以配置为只读模式，禁用所有写操作工具，确保数据安全，防止 LLM 意外修改数据库。
Smithery 集成: 提供通过 Smithery 自动安装和配置的便捷方式，方便 Claude Desktop 等 MCP 客户端集成。

安装步骤

通过 Smithery 安装 (推荐 Claude Desktop 用户): 如果您使用 Claude Desktop 等 MCP 客户端，可以通过 Smithery 命令行工具一键安装。打开终端并执行以下命令：
```
npx -y @smithery/cli install mcp-server-duckdb --client claude
```
Smithery 会自动下载并安装 'mcp-server-duckdb'，并可能进行客户端所需的配置。
手动安装 (开发者或自定义配置): 如果您需要更灵活的配置或用于其他 MCP 客户端，可以手动安装。
- 前提条件: 确保已安装 Python 环境，并安装了 'uv' 包管理器 (可以使用 'pip install uv' 安装)。
- 下载仓库: 下载或克隆 'ktanaka101_mcp-server-duckdb' 仓库的代码到本地。
- 安装 Python 依赖: 在仓库根目录下，使用 'uv' 安装项目依赖 (如果仓库中包含 'requirements.txt' 或 'pyproject.toml' 等依赖描述文件)。通常此仓库依赖较少，可能无需额外手动安装依赖，但如果运行出错，请检查错误信息并安装缺少的包。

服务器配置

MCP 客户端 (如 Claude Desktop) 需要配置 MCP 服务器的启动信息才能连接和使用 'mcp-server-duckdb'。配置信息通常在客户端的配置文件中设置 (例如 Claude Desktop 的 'claude_desktop_config.json')。

以下是 'mcp-server-duckdb' 服务器在 MCP 客户端配置文件中可能的配置信息 (JSON 格式):

{
  "mcpServers": {
    "duckdb_server_name": {  // "duckdb_server_name"：  服务器名称，客户端内唯一标识，可以自定义
      "command": "uvx",      // "command"： 运行服务器的命令，这里使用 uvx (uv 包管理器提供的执行器)
      "args": [             // "args"：  传递给命令的参数列表
        "mcp-server-duckdb", // 第一个参数：  执行 mcp-server-duckdb  (通常是 __init__.py 中定义的 main 函数)
        "--db-path",        // 第二个参数：  指定数据库文件路径的参数名
        "~/path/to/your/duckdb_database.db" // 第三个参数： 数据库文件路径，请替换为实际的 DuckDB 数据库文件路径，可以使用绝对路径或相对路径。
                                         //  例如：  "data/my_database.db" (相对于服务器启动目录) 或 "/home/user/databases/mydb.db"
        // 可以添加更多参数，例如 "--readonly"  启用只读模式
      ]
    }
  }
}

配置参数说明:

'db-path': 必需参数。指定 DuckDB 数据库文件的路径。如果数据库文件不存在，服务器在非只读模式下会自动创建数据库文件及其父目录。在只读模式下，如果数据库文件不存在，服务器将启动失败。
'--readonly': 可选参数。添加此参数后，服务器将以只读模式运行。只读模式下，'write-query' 和 'create-table' 工具将被禁用，防止 LLM 进行任何数据库写操作。如果数据库文件不存在，只读模式下不会创建数据库文件。

重要提示:

请根据您的实际 DuckDB 数据库文件路径修改 '"args"' 中的 '"db-path"' 参数值。
如果您希望以只读模式运行服务器，请在 '"args"' 列表中添加 '" --readonly"'。
'"duckdb_server_name"' 可以自定义，用于在 MCP 客户端中标识该服务器。

基本使用方法

启动 MCP 服务器: 根据上述配置，在 MCP 客户端中启动 'mcp-server-duckdb' 服务器。客户端会根据配置的 'command' 和 'args' 启动服务器进程。
客户端与服务器交互: LLM 客户端 (如 Claude Desktop) 通过 MCP 协议与 'mcp-server-duckdb' 服务器进行通信。客户端可以：
- 列出可用工具: 客户端可以请求服务器列出所有可用的工具 (例如 'read-query', 'write-query', 'list-tables', 'describe-table', 'create-table') 及其描述和输入参数。
- 调用工具: 客户端可以根据需要调用特定工具，并提供工具所需的输入参数。例如，调用 'read-query' 工具时，需要提供要执行的 SQL SELECT 查询语句作为输入。
- 接收工具执行结果: 服务器执行工具后，会将结果以 MCP 协议规定的格式返回给客户端。例如，'read-query' 工具会返回查询结果的文本内容。

示例使用场景:

假设 LLM 需要分析存储在 DuckDB 数据库中的销售数据。它可以：

调用 'list-tables' 工具获取数据库中的表列表，找到包含销售数据的表 (例如 "sales_data" 表)。
调用 'describe-table' 工具获取 "sales_data" 表的结构信息，了解表包含哪些列 (例如 "product_name", "sales_amount", "region" 等)。
调用 'read-query' 工具，并提供 SQL 查询语句，例如: '"SELECT region, SUM(sales_amount) FROM sales_data GROUP BY region ORDER BY SUM(sales_amount) DESC LIMIT 5"'，来查询销售额最高的 5 个地区。
服务器执行查询并将结果返回给 LLM，LLM 可以利用这些数据进行分析、总结或生成报告。

通过 'mcp-server-duckdb'，LLM 可以安全、高效地利用 DuckDB 数据库进行数据分析和处理，扩展 LLM 的应用能力。

关键词