mcp-server-duckdb

这是一个用于DuckDB的模型上下文协议（MCP）服务器实现，通过MCP工具提供数据库交互功能。让LLM对其进行分析会非常有趣。DuckDB适合本地分析。

概述

该服务器通过模型上下文协议与DuckDB数据库进行交互，允许执行数据库操作，如查询、创建表和检查模式。

组件

资源

目前没有实现自定义资源。

提示

目前没有实现自定义提示。

工具

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

• query: 在DuckDB数据库上执行任何SQL查询
  • 输入: query (字符串) - 任何有效的DuckDB SQL语句
  • 输出: 查询结果作为文本（或对于CREATE/INSERT等操作的成功消息）

[!NOTE]
服务器提供了一个统一的query函数，而不是单独的专业化函数，因为现代LLM可以为任何数据库操作（SELECT, CREATE TABLE, JOIN等）生成适当的SQL，而不需要单独的端点。

[!NOTE]
当服务器以readonly模式运行时，将强制执行DuckDB的原生只读保护。
这确保了语言模型（LLM）无法执行任何写操作（CREATE, INSERT, UPDATE, DELETE），从而保持数据完整性和防止意外更改。

配置

必需参数

• db-path (字符串): DuckDB数据库文件的路径
  • 如果数据库文件及其父目录不存在，服务器将自动创建它们
  • 如果指定了--readonly且数据库文件不存在，则服务器将因错误而启动失败

可选参数

• --readonly: 以只读模式运行服务器
  • 描述: 设置此标志后，服务器将以只读模式运行。这意味着：
    • DuckDB数据库将以read_only=True打开，阻止任何写操作。
    • 如果指定的数据库文件不存在，它不会被创建。
    • 安全优势: 防止语言模型（LLM）执行任何写操作，确保数据库不被更改。
  • 参考: 有关DuckDB中只读连接的更多详细信息，请参阅DuckDB Python API文档。

安装

通过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 安装检查工具：

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

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

该检查工具提供了对以下内容的可见性：

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