mcp-server-duckdb

mcp-服务器-duckdb

DuckDB 的模型上下文协议 (MCP) 服务器实现，通过 MCP 工具提供数据库交互功能。如果 LLM 能够对其进行分析，将会非常有趣。DuckDB 适合本地分析。

概述

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

成分

资源

目前，尚未实现自定义资源。

提示

目前，尚未实现自定义提示。

工具

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

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

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

注意：当服务器以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 服务器：

Claude 桌面集成

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

MacOS

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

视窗

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

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

发展

先决条件

• Python 与uv包管理器
• DuckDB Python 包
• MCP 服务器依赖项

调试

由于 MCP 服务器基于 stdio 进行通信，因此调试起来可能颇具挑战性。为了获得最佳调试体验，我们建议使用MCP Inspector 。

使用 MCP 检查器

1. 使用 npm 安装检查器：

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

检查员可以查看以下内容：

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