内容
# DuckDB Local MCP — Agent-Native Data Pipeline
本地 DuckDB MCP Server + dlt 数据管道，复现 MotherDuck Flights 的核心流程：
AI agent 通过 MCP 操作 DuckDB，用 dlt 写声明式管道，cron 自动调度。
**不需要 MotherDuck 账号。不依赖任何云服务。**
## 架构
```
AI Agent (Hermes / Claude / Cursor)
│
├── MCP Server (mcp-server-motherduck)
│ └── 工具: execute_query, list_tables, list_databases, list_columns
│ └── 支持: 本地 .duckdb / :memory: / S3
│
├── dlt (data load tool)
│ └── 声明式管道: schema 演进, 增量 merge, Parquet bulk load
│
└── Cron Scheduler
└── no_agent 模式: 纯脚本执行，零 token 消耗
│
▼
~/data/main.duckdb
```
## 快速开始
### 1. 安装
```bash
# DuckDB MCP Server
uv venv ~/envs/duckdb-mcp
uv pip install --python ~/envs/duckdb-mcp/bin/python mcp-server-motherduck
# dlt 数据管道环境
uv venv ~/envs/dlt
uv pip install --python ~/envs/dlt/bin/python "dlt[duckdb]" httpx pyarrow
```
### 2. 配置 Hermes
在 `~/.hermes/config.yaml` 的 `mcp_servers:` 下添加（注意：YAML 不支持 `~`，需替换为你的实际家目录路径）：
```yaml
duckdb-local:
command: <YOUR_HOME>/envs/duckdb-mcp/bin/mcp-server-motherduck
args:
- --db-path
- <YOUR_HOME>/data/main.duckdb
- --read-write
enabled: true
timeout: 120
connect_timeout: 30
```
重启 Hermes 后即可使用。
### 3. 部署示例 Pipeline
```bash
# 拷贝脚本到 Hermes scripts 目录
cp scripts/github-stars-pipeline.py ~/.hermes/scripts/
# 手动跑一次验证
~/scripts/github-stars-pipeline.py
```
### 4. 注册 dlt-pipeline Skill
```bash
cp -r skills/dlt-pipeline ~/.hermes/skills/devops/dlt-pipeline
```
重启 Hermes 后，agent 可以用自然语言写数据管道。
## MCP 工具
| 工具 | 参数 | 说明 |
|:-----|:-----|:-----|
| `execute_query` | `sql: str` | 执行 SQL 查询（最多 1024 行） |
| `list_tables` | — | 列出所有表和视图 |
| `list_databases` | — | 列出所有已 ATTACH 的数据库 |
| `list_columns` | `table: str` | 列出表的列名和类型 |
## 示例对话
```
你: 查一下 analytics.repos 里 star 最多的 10 个仓库
Agent: [调用 execute_query]
duckdb/duckdb 39,115 ⭐
duckdb/pg_duckdb 3,142 ⭐
duckdb/ducklake 2,826 ⭐
...
你: 帮我写一个 pipeline，每小时从 Hacker News API 拉热门文章到 DuckDB
Agent: [加载 dlt-pipeline skill → 写脚本 → 部署 → 设 cron]
```
## GitHub Stars Pipeline
`scripts/github-stars-pipeline.py` — 定时拉取 DuckDB 组织所有仓库的 star/fork/issue 数据：
```
3 个组织 × 156 个仓库，每小时增量 merge
```
Cron 调度（Hermes）：
```
名称: github-stars-pipeline
脚本: github-stars-pipeline.py
模式: no_agent (纯脚本，零 token)
调度: 0 */6 * * *
```
## 目录结构
```
~/
├── envs/
│ ├── duckdb-mcp/ # mcp-server-motherduck (Python 3.14)
│ └── dlt/ # dlt[duckdb] + httpx + pyarrow
├── data/
│ └── main.duckdb # 数据库文件
├── .hermes/
│ ├── config.yaml # MCP 配置
│ ├── scripts/
│ │ └── github-stars-pipeline.py
│ └── skills/devops/
│ └── dlt-pipeline/
│ └── SKILL.md
└── scripts/
└── github-stars-pipeline.py # 源文件
```
## 与 MotherDuck Flights 的对比
| 维度 | MotherDuck Flights | 本项目 |
|:-----|:-------------------|:-------|
| DuckDB 引擎 | MotherDuck 云 Duckling | 本地 .duckdb |
| MCP 工具 | create_flight, run_flight | execute_query, list_tables |
| 管道部署 | 云端 Python 运行时 | 本地 cron + Python |
| 密钥管理 | MotherDuck Secrets | 环境变量 |
| 版本管理 | Flight 版本历史 | git |
| **费用** | 付费 | **零成本** |
| **隐私** | 数据在云端 | **数据在本地** |
## 依赖
- Python 3.9+
- [mcp-server-motherduck](https://github.com/motherduckdb/mcp-server-motherduck) (MIT)
- [dlt](https://github.com/dlt-hub/dlt) (Apache 2.0)
- [DuckDB](https://duckdb.org/) (MIT)
