DuckDB MCP Extension

关键词

DuckDB 扩展资源管理工具注册HTTP 服务模型上下文协议

使用说明（简明易懂，分步骤描述核心流程）：

  • 项目简介

    • 这是一个将 DuckDB 作为后端的数据源与计算引擎，与 LLM 客户端对接的 MCP 服务实现。它提供托管数据资源、可发现并调用的工具、以及可渲染的提示模板等能力，支持多路传输协议，便于在不同应用场景中与大语言模型进行上下文交互与功能扩展。

  • 主要功能点

    • 作为 MCP 服务器：托管 Resources（数据资源）、Tools（工具）与 Prompts（提示模板），并响应客户端的读取、调用和获取 Prompt 的请求。
    • 传输协议多样性：原生 stdio 传输、HTTP/HTTPS 传输、WebMCP（在浏览器中通过 navigator.modelContext）、以及内存传输等，方便嵌入式与服务端环境。
    • 安全与权限：支持显式的允许命令/URL 的安全策略、服务器锁定、禁用直连请求等，在客户端与服务端导航中实现最小权限原则。
    • 内置与可扩展的工具/资源注册：内置工具集（如 query、describe、database_info、list_tables、export、execute 等）可按需启用，亦支持自定义发布工具、资源、提示模板。
    • Pagination / 缓存与缓存策略：提供分页工具、资源列表等，提升大规模资源/工具集的可用性。

  • 安装与运行步骤

    • 编译与构建
      • 先编译 DuckDB MCP 扩展（在仓库根目录执行 make），生成可执行组件。
    • 启动 MCP 服务器（以 stdio 传输为例）
      • 在 DuckDB 中加载扩展：LOAD 'duckdb_mcp';
      • 启动服务器（stdio 模式，前台示例）： PRAGMA mcp_server_start('stdio'); 说明：这是最基础的启动方式，服务器会在当前 DuckDB 进程内以标准输入/输出进行通信。
    • 启动 HTTP 服务器（可选，带认证）
      • 在 DuckDB 中加载扩展：LOAD 'duckdb_mcp';
      • 启动 HTTP 服务器（带认证示例）： PRAGMA mcp_server_start('http', 'localhost', 8080, '{"auth_token": "secret"}'); 启动后可以通过 HTTP POST 请求与 MCP 客户端进行交互，支持简单鉴权。
    • 作为服务器的配置与客户端配合
      • MCP 客户端需要知道服务器的启动命令与参数，至少包含 command 与 args，以建立与 MCP 服务器的连接。
      • 服务器端也可通过配置项启用健康端点、CORS、日志等特性。

  • 服务器配置（JSON 格式，包含 server name、command、args 等）
    说明：以下字段用于描述一个 MCP 服务器实例在你的环境中的配置。实际运行时，在 DuckDB 的 ATTACH/启动流程中会读取这些参数。请据仓库信息填写到你的系统配置中。示例仅作说明，字段含义见注释。

    { "server_name": "my-duckdb-server", // MCP 服务器名称，用于在 DuckDB 的连接注册与资源/工具的绑定 "transport": "stdio", // 传输协议：可以是 stdio、http、https、memory、webmcp 等 "bind_address": "localhost", // 绑定地址（仅对 TCP/HTTP 等传输生效） "port": 8080, // 绑定端口（仅对 TCP/HTTP 等传输生效） "config_json": "{}", // 服务器全量配置，按需提供，示例：{} 表示默认配置 "command": "duckdb", // 启动后端进程的可执行命令路径（当 transport 需要外部进程时使用） "args": ["-init", "/path/to/init-server.sql"], // 启动命令的参数数组，必要时包含初始化脚本 "cwd": "/path/to/工作目录", // 启动命令的工作目录 "env": { "ENV1": "value1" }, // 启动时传递的环境变量（键值对） "auth_token": "", // HTTP/WebMCP 等场景下的鉴权令牌（如为空则不启用鉴权） "cors_origins": "", // CORS 允许的来源前缀，空字符串表示禁用 CORS "enable_health_endpoint": false, // 是否暴露健康接口 "auth_health_endpoint": false, // 健康接口鉴权开关 "default_result_format": "json", // 默认结果格式（json/jsonl/csv/markdown/text 等） "max_requests": 0, // 最大请求数，0 表示无限制 "require_auth": false, // 是否强制鉴权（与传输层配合实现） "ssl_cert_path": "", // 对应 https 的证书路径（若启用 https） "ssl_key_path": "" // 对应 https 的证书私钥路径 }

    说明：实际使用时，请将 server_name、transport、command、args、cwd、env、鉴权与 CORS 等字段配置为你自己的环境与需求。MCP 客户端本身不需要包含服务器配置信息，但你需要通过服务器端提供的参数来建立连接。

  • 基本使用方法

    • 连接与查询资源
      • 加载扩展并启动 MCP 服务器后，客户端可以通过 MCP 的资源读取接口查询 DuckDB 中的公开数据表或发布的资源内容。
    • 注册工具与读取资源
      • LLM 客户端可以通过 Tools 的注册过程发现可用工具，或通过发布工具的方式将自定义 SQL 任务暴露给模型调用。
    • HTTP 访问与安全
      • 如果使用 HTTP/HTTPS 传输，请配置鉴权令牌，按需开启 CORS，确保模型端能够访问。
    • 使用示例总结
      • 你可以在 DuckDB 中执行 LOAD 'duckdb_mcp'; 之后根据需要通过 PRAGMA 或 mcp_server_start 启动 server，模型端通过 MCP 的客户端函数与服务端进行资源、工具、提示模板等的交互。

  • 重要注意

    • 服务器端实现包含多种传输模式、资源/工具的发布与读取、提示模板管理、分页支持等能力，且具备基本的安全模型（如命令白名单、URL 白名单、不可变性等策略），符合 MCP 的服务器目标。
    • 该仓库内还包含大量测试和示例服务器（作为测试用例或演示），但核心实现确实提供了完整的 MCP 服务器端功能、协议处理与多传输实现。

  • 使用场景建议

    • 将 DuckDB 作为强大数据源和计算引擎，向大型语言模型对接，使用 MCP 提供的资源、工具与 prompts 来实现“查询数据、分析数据、调用外部功能”的能力组合，并通过 HTTP/stdio/WebMCP 等方式对接云端或本地的 AI 助手。
    • 结合 GUI/IDE 配置和 Claude/Azure/OpenAI 等大模型进行智能数据查询、数据描述、报表生成等工作流。

服务器信息

访问项目