JinDaGe - mcp-server-duckdb MCP Details

article

README

🚀 mcp-server-duckdb

一个为DuckDB实现的模型上下文协议（MCP）服务器，它能提供通过MCP工具进行数据库交互的能力。DuckDB非常适合本地分析。

🚀 快速开始

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

✨ 主要特性

资源

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

提示语

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

工具

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

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

⚠️ 重要提示

该服务器提供一个统一的query函数，而不是单独的专业化功能，因为现代大语言模型（LLM）可以为任何数据库操作生成适当的SQL语句（如SELECT、CREATE TABLE、JOIN等），而无需分别指定端点。

⚠️ 重要提示

当服务器以只读模式运行时，DuckDB的内置只读保护将被启用。这意味着语言模型（LLM）无法执行任何写入操作（如CREATE、INSERT、UPDATE、DELETE），从而保持数据完整性并防止意外更改。

📦 安装指南

通过以下命令安装：

uvx add mcp-server-duckdb

在Claude Desktop上进行集成时，请将以下内容添加到~/.config/claude.yaml：

mcp:
  servers:
    - duckdb:
        class_path: mcp_server_duckdb.DuckDBMCPHandler

💻 使用示例

基础用法

在Claude Desktop上使用时，可以通过以下命令运行：

uvx serve --port 12345 duckdb:mcp-server-duckdb

然后在Claude Desktop中配置MCP端点为http://localhost:12345

高级用法

通过以下命令启动调试服务器：

uvx debug duckdb:mcp-server-duckdb

该调试器提供以下功能：

请求/响应通信的可见性
工具执行的跟踪
服务器状态监控
错误消息显示

📚 详细文档

配置

必要参数

db-path（字符串）：DuckDB数据库文件的路径
- 服务器将自动创建数据库文件及其父目录，如果它们不存在
- 如果指定--readonly且数据库文件不存在，服务器将无法启动并显示错误

可选参数

--readonly：以只读模式运行服务器
- 描述：当此标志设置时，服务器将以只读模式运行。这意味着：
  - DuckDB数据库将以read_only=True打开，阻止任何写入操作。
  - 如果指定的数据库文件不存在，则不会创建它。
  - 安全性优势：防止语言模型（LLM）执行任何写入操作，确保数据安全
- 参考：DuckDB文档

📄 许可证

文档中未明确提及具体许可证内容，但通过https://img.shields.io/pypi/l/mcp-server-duckdb链接可查看相关许可证信息。

mcp-server-duckdb