quantdb-mcp

量化金融数据库 + 只读 SQL MCP 服务。

• 数据源：easy-tdx（通达信 TCP 行情）+ pywestockdata（腾讯/东财基本面 HTTP）
• 存储：DuckDB 双文件 —— quantdb_ods.duckdb（ODS 原始层）/ quantdb.duckdb（DWD 层，清洗后）
• 接口：FastMCP streamable-http 只读 query(sql) 工具（可跨库 JOIN）

分层架构

层	库文件	表
ODS	quantdb_ods.duckdb	stock_basic / daily_kline / realtime_quote / finance_income / finance_balance / finance_cashflow
DWD	quantdb.duckdb	dim_stock（去重标准化）/ fact_daily（列名统一）
APP	-	后续因子层（可复用 factor-pipeline 表达式引擎）

ODS 可整体重灌，DWD 由 sync_dwd 全量重建（幂等）。

安装

cd projects/quantdb-mcp
uv sync                       # 或 pip install -e .

依赖：duckdb、fastmcp、pywestockdata、easy-tdx、click。

CLI

quantdb init                  # 建库建表（双文件）
quantdb full-load             # 全量同步：代码表 → 日K → 财务 → DWD 重建
quantdb full-load --codes 50 --kline-count 120   # 限前 50 只、每只 120 根K线（试跑用）
quantdb update --once         # 增量同步 + 一次实时快照
quantdb update                # 盘中 30s 快照循环（Ctrl+C 退出）
quantdb summary               # 各表行数与最新日期

数据目录通过环境变量 QUANTDB_DATA_DIR 指定（默认 ./data）。

MCP 接入

启动服务（streamable-http）：

uv run python -m quantdb.server.mcp   # 等价 pip 安装后的 quantdb-mcp

注册到 MCP 客户端（如 nanobot / Claude Desktop）：

{
  "mcpServers": {
    "quantdb": {
      "command": "quantdb-mcp",
      "type": "stdio"
    }
  }
}

查询示例（query 工具，只读）：

SELECT * FROM dim_stock WHERE market = 'sh' LIMIT 5
SELECT d.code, s.name, d.close FROM fact_daily d JOIN ods.stock_basic s ON d.code = s.code
  WHERE d.date = (SELECT max(date) FROM fact_daily)

安全限制

• 仅允许单条 SELECT / WITH；写语句、多语句被拒绝
• 表白名单：仅业务表（ODS 用 ods. 前缀），内部表不可见
• 最多返回 10_000 行；查询超时 30s；DuckDB 以只读模式打开

测试

uv run pytest                    # 97 tests，100% 覆盖率（mock 数据源，不依赖网络）
uv run ruff check src tests      # 0 error

详见 design.md 与 task_list.md。