mcp-server-duckdb

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

<a href="https://glama.ai/mcp/servers/fwggl49w22"><img width="380" height="200" src="https://glama.ai/mcp/servers/fwggl49w22/badge" alt="mcp-server-duckdb MCP server" /></a>

概述

此服务器通过模型上下文协议启用与 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 Server：

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 安装 inspector：

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

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

inspector 提供以下方面的可见性：

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