DuckDB MCP 服务器

一个实现了模型上下文协议（MCP）的服务器，它使像 Claude 这样的 AI 助手能够与 DuckDB 交互，从而获得强大的数据分析能力。

🌟 DuckDB MCP 服务器是什么？

DuckDB MCP 服务器通过 模型上下文协议 (MCP) 将 AI 助手连接到 DuckDB —— 一个高性能的分析数据库。这允许 AI 模型：

• 直接从各种来源如 CSV、Parquet、JSON 等查询数据
• 无需复杂设置即可从云存储（S3 等）访问数据
• 使用 SQL 执行复杂的数据分析
• 以正确的上下文和理解生成数据洞察

🚀 主要特性

• SQL 查询工具：使用 DuckDB 强大的语法执行任何 SQL 查询
• 多数据源：直接从以下位置查询：
  • 本地文件（CSV、Parquet、JSON 等）
  • S3 存储桶和云存储
  • SQLite 数据库
  • DuckDB 支持的所有其他数据源
• 自动连接管理：自动创建数据库文件并处理连接
• 智能凭证处理：无缝 AWS/S3 凭证管理
• 文档资源：内置的 DuckDB SQL 和数据导入参考供 AI 助手使用

📋 要求

• Python 3.10+
• 一个支持 MCP 的客户端（Claude Desktop、Cursor、带有 Copilot 的 VS Code 等）

💻 安装

使用 pip

pip install duckdb-mcp-server

从源代码安装

git clone https://github.com/yourusername/duckdb-mcp-server.git
cd duckdb-mcp-server
pip install -e .

🔧 配置

命令行选项

duckdb-mcp-server --db-path path/to/database.db [options]

必需参数：

• --db-path - DuckDB 数据库文件路径（如果不存在则会创建）

可选参数：

• --readonly - 以只读模式运行（如果数据库不存在则会报错）
• --s3-region - AWS S3 区域（默认：使用 AWS_DEFAULT_REGION 环境变量）
• --s3-profile - 用于 S3 凭证的 AWS 配置文件（默认：使用 AWS_PROFILE 或 'default'）
• --creds-from-env - 从环境变量中使用 AWS 凭证

🔌 与 Claude Desktop 设置

1. 从 claude.ai/download 下载并安装 Claude Desktop

2. 编辑 Claude Desktop 的配置文件：

   macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   Windows: %APPDATA%/Claude/claude_desktop_config.json

3. 添加 DuckDB MCP 服务器配置：

{
  "mcpServers": {
    "duckdb": {
      "command": "duckdb-mcp-server",
      "args": [
        "--db-path",
        "~/claude-duckdb/data.db"
      ]
    }
  }
}

📊 示例用法

配置完成后，您可以要求您的 AI 助手使用 DuckDB 分析数据：

"Load the sales.csv file and show me the top 5 products by revenue"

AI 将生成并执行适当的 SQL：

-- Load and query the CSV data
SELECT 
    product_name,
    SUM(quantity * price) AS revenue
FROM read_csv('sales.csv')
GROUP BY product_name
ORDER BY revenue DESC
LIMIT 5;

处理 S3 数据

直接从 S3 存储桶查询数据：

"Analyze the daily user signups from our analytics data in S3"

AI 将生成适当的 SQL 来查询 S3：

SELECT 
    date_trunc('day', signup_timestamp) AS day,
    COUNT(*) AS num_signups
FROM read_parquet('s3://my-analytics-bucket/signups/*.parquet')
GROUP BY day
ORDER BY day DESC;

🌩️ 云存储认证

DuckDB MCP 服务器按此顺序处理 AWS 认证：

1. 明确的凭证（如果启用了 --creds-from-env）
2. 命名配置文件凭证（通过 --s3-profile）
3. 默认凭证链（环境、共享凭证文件等）

🛠️ 开发

# Clone the repository
git clone https://github.com/yourusername/duckdb-mcp-server.git
cd duckdb-mcp-server

# Set up a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

📜 许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

🙏 贡献

欢迎贡献！请随时提交 Pull Request。