mcp-server-duckdb

mcp-server-duckdb

DuckDB 的模型上下文协议（MCP）服务实现，可通过 MCP 工具提供数据库交互功能。 让大模型来分析它会很有意思。DuckDB 适用于本地分析。

概览

此服务通过模型上下文协议支持与 DuckDB 数据库交互，可执行查询、创建表和检查架构等数据库操作。

组件

资源

目前未实现自定义资源。

提示词

目前未实现自定义提示词。

工具

此服务实现了以下数据库交互工具：

• query：在 DuckDB 数据库上执行任意 SQL 查询
  • 输入：query（字符串）——任意有效的 DuckDB SQL 语句
  • 输出：查询结果文本（对于 CREATE/INSERT 等操作，则返回成功消息）

说明

此服务提供一个统一的 query 函数，而非多个专用函数，因为现代大模型可以为任何数据库操作（SELECT、CREATE TABLE、JOIN 等）生成合适的 SQL，无需单独的端点。

说明

当服务以 readonly 模式运行时，将启用 DuckDB 原生的只读保护。 这可确保语言模型（LLM）无法执行任何写入操作（CREATE、INSERT、UPDATE、DELETE），从而维护数据完整性并防止意外更改。

配置

必需参数

• db-path（字符串）：DuckDB 数据库文件的路径
  • 如果数据库文件及其父目录不存在，服务会自动创建
  • 如果指定了 --readonly，而数据库文件不存在，服务将报错并无法启动

可选参数

• --readonly：以只读模式运行服务（默认值：false）
  • 说明：设置此标志后，服务将以只读模式运行。这意味着：
    • DuckDB 数据库将以 read_only=True 打开，禁止任何写入操作。
    • 如果指定的数据库文件不存在，则不会创建该文件。
    • 安全优势：防止语言模型（LLM）执行任何写入操作，确保数据库不被修改。
  • 参考：有关 DuckDB 只读连接的详细信息，请参阅 DuckDB Python API 文档。
• --keep-connection：复用单个 DuckDB 连接模式（默认值：false）
  • 说明：设置此标志后，在服务的整个生命周期内复用单个 DuckDB 连接。支持 TEMP 对象，并能略微加快查询速度，但可能会对文件持有独占锁。

安装

通过 Smithery 安装

通过 Smithery 自动为 Claude Desktop 安装 DuckDB 服务：

npx -y @smithery/cli install mcp-server-duckdb --client claude

集成 Claude Desktop

在 Claude Desktop 的配置文件中配置 MCP 服务：

MacOS

位置：~/Library/Application Support/Claude/claude_desktop_config.json

Windows

位置：%APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "duckdb": {
      "command": "uvx",
      "args": [
        "mcp-server-duckdb",
        "--db-path",
        "~/mcp-server-duckdb/data/data.db"
      ]
    }
  }
}

• 注意：~/mcp-server-duckdb/data/data.db 应替换为 DuckDB 数据库文件的实际路径。

开发

先决条件

• 安装了 uv 包管理器的 Python
• DuckDB Python 包
• MCP 服务依赖项

调试

由于 MCP 服务通过 stdio 进行通信，调试起来可能颇具挑战。我们建议使用 MCP Inspector，以获得最佳调试体验。

使用 MCP Inspector

1. 使用 npm 安装 inspector：

npx @modelcontextprotocol/inspector uv --directory ~/codes/mcp-server-duckdb run mcp-server-duckdb --db-path ~/mcp-server-duckdb/data/data.db

2. 在浏览器中打开提供的 URL，以访问调试界面

Inspector 可展示以下内容：

• 请求/响应通信
• 工具执行
• 服务状态
• 错误消息