mcp-server-duckdb

一个用于DuckDB的模型上下文协议（MCP）服务器实现，通过MCP工具提供数据库交互功能。让LLM分析它将很有趣。DuckDB适合本地分析。

概述

该服务器通过模型上下文协议（MCP）实现与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：以只读模式运行服务器（默认：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

使用npm安装inspector：

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

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

Inspector提供对以下内容的可见性：

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

ktanaka101/mcp-server-duckdb

星标增长

证据时间轴