🚀 mcp-server-duckdb

这是一个为DuckDB实现的模型上下文协议（MCP）服务器，它提供了通过MCP工具进行数据库交互的能力。DuckDB非常适合本地分析，借助此服务器，用户能够更便捷地与DuckDB数据库进行交互操作。

🚀 快速开始

本服务器通过模型上下文协议（MCP）与DuckDB数据库进行交互，支持查询、表创建和架构检查等数据库操作。你可以按照以下步骤快速使用该服务器：

安装

通过以下命令安装：

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

该调试器提供以下功能：

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

✨ 主要特性

• 统一查询接口：服务器提供一个统一的query函数，现代大语言模型（LLM）可以为任何数据库操作生成适当的SQL语句（如SELECT、CREATE TABLE、JOIN等），而无需分别指定端点。
• 只读模式保护：当服务器以只读模式运行时，DuckDB的内置只读保护将被启用，语言模型（LLM）无法执行任何写入操作（如CREATE、INSERT、UPDATE、DELETE），从而保持数据完整性并防止意外更改。

📦 安装指南

必要参数

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

可选参数

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

💻 使用示例

基础用法

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

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

# 以下是使用query工具的示例
# 假设已经正确配置并启动了服务器
# 这里只是示意代码，实际使用时需要根据具体情况调整
import requests

# 假设MCP端点为http://localhost:12345
url = "http://localhost:12345"
query = "SELECT * FROM your_table"
data = {
    "query": query
}
response = requests.post(url, json=data)
print(response.text)

高级用法

在实际应用中，你可以结合大语言模型（LLM）来使用该服务器。例如，让LLM根据需求生成SQL语句，然后通过query工具执行这些语句。

# 假设已经有一个可以生成SQL语句的LLM
# 这里只是示意代码，实际使用时需要根据具体情况调整
import requests
from your_llm_module import generate_sql

# 假设MCP端点为http://localhost:12345
url = "http://localhost:12345"
# 让LLM生成SQL语句
sql = generate_sql("查询所有用户信息")
data = {
    "query": sql
}
response = requests.post(url, json=data)
print(response.text)

📚 详细文档

组件

资源

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

提示语

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

注意事项

⚠️ 重要提示

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

⚠️ 重要提示

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

📄 许可证

查看许可证信息请点击：PyPI - 许可证