Local Datasource

一个本地运行的 MCP（Model Context Protocol）数据服务器。它让任何支持 MCP 的 Agent（Claude Code、Codex、Cursor、OpenCode 等）都能直接查询金融市场、宏观经济和学术论文数据，而无需第三方账号、不消耗云额度、不经过外部中继。

一句话介绍

local-datasource 把 akshare、yfinance、wbgapi、arxiv 等免费公开接口封装成 16 个标准 MCP tool，覆盖 A股/港股/美股/ETF/期货/指数/期权行情、债券与可转债、全球利率与波动率（美债收益率/美联储利率/美元指数/VIX）、汇率、商品现货、带生效区间的交易规则参数表、多序列对齐合并、世界银行宏观指标与 arXiv 论文，Agent 只需要像调用本地函数一样请求数据，即可获得结构化 CSV 输出。

为什么需要这个项目

在日常投研、尽调、学术检索或自动化报告生成中，Agent 经常需要实时数据：

• 查一只股票过去一年的走势

• 对比黄金、美股、A股等多资产表现

• 拉取某个国家的 GDP/CPI 数据

• 检索某个领域的 arXiv 论文

这些需求本身并不复杂，但常见方案要么需要登录某个平台并消耗额度，要么把查询请求发到云端。local-datasource 希望提供一种透明、可控、低成本的替代方案：

• 数据请求不出本机：适合对合规、隐私敏感的场景。

• 无需账号和额度：基于公开接口，安装完就能用。

• 标准 MCP 协议：不绑定任何特定 Agent，可被多家产品复用。

• 源码可见、可扩展：增加新数据源或调整输出格式都很直接。

核心特点

• ✅ A股 / 港股 / 美股：日线行情，支持前复权/后复权。

• ✅ 美股 / 美股 ETF / 全球资产：默认 akshare 美股接口，可回退 yfinance（A股场内 ETF 见 query_etf）。

• ✅ 世界银行宏观指标：GDP、CPI、人口等。

• ✅ arXiv 论文搜索：标题、作者、摘要、PDF 链接结构化输出。

• ✅ 中国境内债券：国债收益率曲线、信用债发行信息（按代码或发行人查）、交易所行情。

• ✅ 可转债：一览含溢价率、强赎/回售条款、历史K线、发行人正股财务报表。

• ✅ 国内期货：单合约（全历史）/主连日线与分钟、品种挂牌合约清单。

• ✅ 国内指数：沪深指数（2014 起）与中证系列日线，沪深指数分钟。

• ✅ A股场内 ETF：日线（2012 起全历史）与分钟。

• ✅ 期权：ETF 期权与股指期权（IO/HO/MO）的到期月份、合约清单、单合约日线。

• ✅ A股个股分钟：query_stock(period=min)，与日线同一入口。

• ✅ 全球利率与波动率：美债收益率曲线、美联储 EFFR、美元指数（东财失败回退 Yahoo）、VIX（CBOE 直连）。

• ✅ 汇率：央行官方中间价、中行牌价、离岸 USDCNH、主要货币对交叉盘。

• ✅ 商品现货：上金所贵金属日线、生意社大宗现货（含主力合约价与基差）。

• ✅ 对齐合并：多份本库产出的 CSV 按日期合并成宽表（支持周/月重采样），纯本地计算。

• ✅ 交易规则参数表：印花税/过户费/涨跌幅/保证金/T+1 等参数按 as_of 取当日生效值（含生效区间、来源与四档置信度标注）；商品期货参数不入表、返回查交易所当日结算参数的引导。

• ✅ 金融输入归一化：股票/债券的名称、简称、全称、发行人 → 统一代码（resolve_stock_code + bond_issue）。

• ✅ 统一 CSV 输出：每个 tool 都把结果写到 file_path，并返回前 5 行预览。

• ✅ 零 API Key：所有默认数据源均免费使用。

• ✅ 跨 Agent 复用：标准 MCP Server，配置一条 command 即可接入。

适用人群

• 需要在 Agent 工作流里频繁查数据的投研、分析师、开发者。

• 不希望把查询请求发送到云端的本地优先用户。

• 想学习/定制 MCP 数据服务器实现的开发者。

快速开始

要求：Python >= 3.10。

# 1. 克隆并安装
git clone https://github.com/jarvislee90s-dot/local-datasource.git
cd local-datasource
pip install -e .

# 2. 启动 MCP 服务
local-datasource

# 3. 在 Agent 的 MCP 配置中添加
{
  "mcpServers": {
    "local-datasource": {
      "command": "local-datasource"
    }
  }
}

覆盖范围

金融输入归一化

用户给金融标的时可能贴代码、简称、全称或发行人名。本服务支持先把输入归一化为统一代码再查询：

• 股票：公司简称/全称 → resolve_stock_code → 代码候选 → query_stock（新浪 suggest API 支持全称反查）

• 标债：发行人名 → query_bond(kind=issue_info, bond_issue=...) → 最新一只债代码 → 继续查基本信息/财务

• 可转债：正股简称 → query_convertible_bond(kind=overview, keyword=...) → 该公司转债

• 发行人财务：任意债代码/发行人名 → 先归一化到代码 → query_convertible_bond(kind=issuer_finance, ...)

• 期货：直接给合约/主连代码（IM2612/IM0/IM主连 自动归一）；查挂牌合约用 query_futures(kind=contracts, symbol=品种如IM)（合约清单走交易所官方挂牌表，DCE/GFEX 品种忽略 trade_date，返回当前挂牌）

• 指数：000852/sh000300 自动补交易所前缀走新浪；中证系列 930xxx/950xxx 自动走中证官网源（慢约 10 秒，无分钟）

• ETF：510300 按首位自动补 sh/sz 前缀

• 期权：先 query_options(kind=months/contracts, underlying=...) 拿到期月份/合约代码，再 kind=hist 查日线；合约代码宽容格式（IO2706-P-5600 与 io2706p5600 等价）

城投/非上市发行人无上市股票，resolve_stock_code 返回空候选；其债券的 issuer_finance 返回引导性提示（免费层无财务，建议查 Wind/企业预警通）。

架构

Agent（Claude Code / Codex / Cursor / OpenCode 等）
        ↓ MCP stdio
local-datasource（本仓库）
        ↓ 直接调用
akshare / yfinance / wbgapi / arxiv / requests（HTTP 直连）
        ↓ 原始数据源
新浪 / 腾讯 / 东财数据中心 / 交易所官网 / 中证指数 / 同花顺 / 外汇局 / 上金所 / 生意社 / 纽约联储 / CBOE / Yahoo Finance / World Bank / arxiv.org

文件结构

.
├── SKILL.md                        # Agent 执行手册
├── README.md                       # 项目介绍（本文档）
├── CHANGELOG.md                    # 里程碑变更记录
├── pyproject.toml                  # Python 包配置与依赖
├── config.yaml                     # 可选配置文件
├── src/local_datasource/           # MCP server 源码
│   ├── server.py                   # 服务入口：注册 tools、处理调用
│   ├── cli.py                      # download 批量下载子命令（唯一写缓存的入口）
│   ├── cache.py                    # 下载缓存纯函数：key/路径/manifest/新鲜度
│   ├── config.py                   # 加载 config.yaml / 环境变量
│   ├── formatters.py               # 统一 CSV 输出与预览
│   ├── assets/
│   │   └── trading_rules.yaml      # 交易规则参数静态表（附录 B 调研，随包分发）
│   └── providers/                  # 各数据源适配器
│       ├── common.py               # 共享工具：日期过滤、分钟深度守卫、腾讯分钟路径
│       ├── stock.py                # A/HK/US 股票（日线/A股分钟）+ resolve_stock_code 名称反查
│       ├── yahoo.py                # 美股/全球资产
│       ├── worldbank.py            # 世界银行
│       ├── arxiv.py                # arXiv 论文
│       ├── bond.py                 # 中国境内债券（国债收益率/信用债发行/交易所行情）
│       ├── convertible_bond.py     # 可转债（一览/条款/历史K线/发行人财务）
│       ├── futures.py              # 国内期货（行情/合约清单）
│       ├── index.py                # 国内指数（沪深/中证系列）
│       ├── etf.py                  # A股场内 ETF
│       ├── options.py              # 期权（ETF/股指：月份/清单/日线）
│       ├── global_rates.py         # 全球利率（美债收益率/美联储 EFFR/美元指数/VIX）
│       ├── fx.py                   # 外汇（中间价/中行牌价/离岸 USDCNH/交叉盘）
│       ├── spot.py                 # 现货（上金所贵金属/生意社大宗含基差）
│       ├── align.py                # 多序列对齐合并（宽表/重采样，纯本地）
│       └── rules.py                # 交易规则参数表（按 as_of 取生效值，纯本地）
└── demos/                          # 示例脚本
    └── mcp_query_demo.py           # 多资产查询 + 归一化走势图

依赖

• Python >= 3.10

• mcp：MCP 服务器框架

• akshare：A股/港股/美股/ETF/债券/可转债 行情

• yfinance：Yahoo Finance 备选接口

• wbgapi：世界银行数据

• arxiv：arXiv 论文搜索

• pandas：数据处理

• pyyaml：配置文件解析

• requests：新浪 suggest API（股票名称反查）

可选：

• matplotlib：运行 demos/mcp_query_demo.py 绘图

安装

pip install -e .

安装完成后，local-datasource 命令会被加入 PATH。

启动 MCP 服务

local-datasource

服务通过标准输入输出（stdio）与 Agent 通信。可以用以下命令快速验证是否启动成功：

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | local-datasource

若返回初始化结果，说明服务正常。

批量下载（download 命令）

除了作为 MCP 服务被 Agent 调用，本库还提供一个批量下载子命令，把常用数据在本地预取成 CSV 缓存，供回测、研究复用：

local-datasource download --config FILE [--data-dir DIR] [--force]

• --config（必填）：清单 YAML 路径

• --data-dir：缓存根目录；优先级 CLI --data-dir > 清单顶层 data_dir > config.yaml 的 cache.data_dir

• --force：忽略"当天已拉取"的新鲜度判断，强制重新下载

清单 YAML 格式（assets 列表，每条 {tool, args, start_date?, end_date?}）：

# batch.yaml
data_dir: ./datasource-cache   # 顶层可选；CLI --data-dir 优先
assets:
  - tool: query_global_rates
    args: {kind: us_treasury, tenure: all}
  - tool: query_stock
    args: {ticker: "600519", market: a, adjust: qfq, period: daily}
    start_date: "2025-01-01"   # 可选：合并进 args；与 args 内同名值同时存在时,这里优先
    end_date: "2025-12-31"
  - tool: query_fx
    args: {kind: mid, currency: usd,eur}

支持的 tool 白名单为 13 个查询工具（query_stock/query_yfinance/query_worldbank/query_arxiv/query_bond/query_convertible_bond/query_futures/query_index/query_etf/query_options/query_global_rates/query_fx/query_spot）。resolve_stock_code（名称反查）、align_series（本地对齐）、query_trading_rules（M4 静态规则表）不支持出现在清单中——它们不产出待缓存的行情序列。未知 tool 名、缺 args 会在启动时一次性报错并列出合法 tool 名，校验全部通过后才开始下载。

每条目输出一行状态：

• SKIP <tool>/<key>：当天已拉取过（manifest 的 last_fetched 为今天）且未 --force，直接复用缓存

• FETCH <tool>/<key> <rows> rows：调用 provider 下载并写入缓存

• FAIL <tool>/<key> <error>：该条目失败；单条失败不中断整批，全部条目跑完后只要存在失败，退出码为 1（全部成功 0，清单/用法错误 2）

缓存目录布局：每条目落在 <data_dir>/<tool>/<key>.csv，旁边有同名的 <key>.manifest.json 元信息（含 args、行数、首末日期、last_fetched）。key 由工具名与参数生成，可读且末尾带 8 位哈希，例如：

datasource-cache/
└── query_global_rates/
    ├── query_global_rates-kind-us_treasury-tenure-all-1a2b3c4d.csv
    └── query_global_rates-kind-us_treasury-tenure-all-1a2b3c4d.manifest.json

架构说明：MCP 查询路径不做任何缓存，永远直连数据源；download 是唯一写缓存的入口。缓存仅供用户显式预取/复用，不会让 Agent 拿到过期数据。

Agent 配置示例

任何支持 MCP 的 Agent 都可以通过 command 方式调用本服务。

Claude Code

claude_mcp_settings.json：

{
  "mcpServers": {
    "local-datasource": {
      "command": "local-datasource"
    }
  }
}

Codex

.codex/config.json：

{
  "mcpServers": {
    "local-datasource": {
      "command": "local-datasource"
    }
  }
}

Cursor / Windsurf / OpenCode

在对应 MCP 配置中添加：

{
  "mcpServers": {
    "local-datasource": {
      "command": "local-datasource"
    }
  }
}

调用数据案例

查询 A 股：贵州茅台

{
  "ticker": "600519",
  "market": "a",
  "start_date": "2025-06-01",
  "end_date": "2026-06-24",
  "file_path": "/tmp/moutai.csv"
}

Tool：query_stock

查询港股：腾讯

{
  "ticker": "00700",
  "market": "hk",
  "start_date": "2025-06-01",
  "end_date": "2026-06-24",
  "file_path": "/tmp/tencent.csv"
}

Tool：query_stock

查询美股/ETF：黄金 GLD

{
  "ticker": "GLD",
  "period": "1y",
  "file_path": "/tmp/gld.csv"
}

Tool：query_yfinance

默认使用 akshare 的美股日线接口；若需要 Yahoo Finance 数据，添加 "use_yfinance": true：

{
  "ticker": "AAPL",
  "period": "1y",
  "use_yfinance": true,
  "file_path": "/tmp/aapl_yahoo.csv"
}

查询世界银行：中国 GDP 现价

{
  "indicator": "NY.GDP.MKTP.CD",
  "country": "CHN",
  "start_year": 2020,
  "end_year": 2023,
  "file_path": "/tmp/china_gdp.csv"
}

Tool：query_worldbank

搜索 arXiv 论文

{
  "query": "large language model retrieval augmented generation",
  "max_results": 10,
  "sort_by": "relevance",
  "file_path": "/tmp/llm_rag.csv"
}

Tool：query_arxiv

查询国债收益率曲线

{
  "kind": "yield_curve",
  "start_date": "2025-01-01",
  "end_date": "2025-06-30",
  "file_path": "/tmp/bond_yield.csv"
}

Tool：query_bond（kind=yield_curve）

查询信用债发行信息

{
  "kind": "issue_info",
  "bond_code": "2180495.IB",
  "file_path": "/tmp/bond_issue.csv"
}

Tool：query_bond（kind=issue_info，bond_code 精确匹配单只，支持 2180495.IB / 2180495 格式，避免子串误命中）

按发行人查最新一只债

{
  "kind": "issue_info",
  "bond_issue": "成都东方广益",
  "file_path": "/tmp/bond_by_issuer.csv"
}

Tool：query_bond（kind=issue_info，bond_issue 按发行人查，返回发行日期最新的一只债代码；与 bond_code 互斥）

查询可转债一览

{
  "kind": "overview",
  "file_path": "/tmp/cb_overview.csv"
}

Tool：query_convertible_bond（kind=overview，返回全市场转债含转股溢价率/评级/规模，可选 keyword 按简称过滤）

查询发行人财务报表

{
  "kind": "issuer_finance",
  "stock_code": "sh603938",
  "report_type": "资产负债表",
  "file_path": "/tmp/issuer_finance.csv"
}

Tool：query_convertible_bond（kind=issuer_finance，bond_code/stock_code 二选一；城投/非上市发行人返回引导性提示而非报错）

股票名称反查代码

{
  "keyword": "贵州茅台酒股份有限公司",
  "file_path": "/tmp/resolve_stock.csv"
}

Tool：resolve_stock_code（首选新浪 suggest API，简称精确命中、全称从关联字段提取代码；城投/非上市发行人返回空候选；多候选时择一再调 query_stock）

查询期货：IM 主连日线

{
  "symbol": "IM0",
  "period": "daily",
  "start_date": "2026-06-01",
  "end_date": "2026-08-28",
  "file_path": "/tmp/im_main.csv"
}

Tool：query_futures（单合约改 symbol: IM2612 得全历史；分钟加 period: min，深度约 4 个交易日，超覆盖报错并给补数指引）

查询指数：中证1000 日线

{
  "symbol": "000852",
  "period": "daily",
  "start_date": "2014-10-17",
  "end_date": "2026-08-28",
  "file_path": "/tmp/csi1000.csv"
}

Tool：query_index（中证系列 930xxx 走中证官网源，慢约 10 秒、无分钟数据）

查询 ETF：沪深300ETF 分钟

{
  "symbol": "510300",
  "period": "min",
  "freq": "1",
  "start_date": "2026-08-25",
  "end_date": "2026-08-27",
  "file_path": "/tmp/etf_min.csv"
}

Tool：query_etf（日线去 period/freq 加日期区间；日线源无复权）

查询期权：IO 到期月份 → 单合约日线

{
  "kind": "months",
  "underlying": "IO",
  "file_path": "/tmp/io_months.csv"
}

Tool：query_options（合约清单 kind: contracts；日线 kind: hist, symbol: "IO2706-P-5600"）

查询美债收益率

{
  "kind": "us_treasury",
  "tenure": "all",
  "file_path": "/tmp/us_treasury.csv"
}

Tool：query_global_rates（kind=us_treasury，tenure: all 返回 2/5/10/30 年及 10Y-2Y 利差，1990 年起；短端期限如 3m 仅近 1000 交易日；kind=fed_rate/dxy/vix 分别查美联储 EFFR、美元指数（东财失败自动回退 Yahoo）、VIX（CBOE 直连，1990 起））

查询汇率中间价

{
  "kind": "mid",
  "currency": "usd,eur",
  "file_path": "/tmp/fx_mid.csv"
}

Tool：query_fx（kind=mid 外汇局官方中间价，1994 年起，单位为 100 外币 = X 人民币；kind=bochina 中行牌价需 symbol 如"美元"且起止日期必填；kind=usdcnh/cross 走 Yahoo，不可达时明确报错）

查询现货黄金：上金所 Au99.99

{
  "kind": "sge",
  "symbol": "Au99.99",
  "file_path": "/tmp/au9999.csv"
}

Tool：query_spot（kind=sge 上金所贵金属日线，2016-12 起约 10 年深度；kind=sy 生意社大宗现货含主力合约价与基差，需 symbols: ["CU","RB"] 且起止日期必填、单次区间最长 1 年）

对齐合并多份行情 CSV 为宽表

{
  "file_paths": ["/tmp/moutai.csv", "/tmp/gld.csv"],
  "columns": ["close", "close"],
  "names": ["moutai", "gld"],
  "align": "outer",
  "fill": "ffill",
  "file_path": "/tmp/merged.csv"
}

Tool：align_series（纯本地合并不联网；columns/names 与 file_paths 一一对应，缺省各取 close、列名用文件名；resample: "week"/"month" 重采样时每期取最后一个实际交易日）

查询交易规则参数：A 股某历史日期的印花税

{
  "market": "a",
  "as_of": "2021-06-01",
  "file_path": "/tmp/rules_a.csv"
}

Tool：query_trading_rules（纯本地读包内静态表；不传 as_of 取现行值；market: "commodity_futures" 返回查交易所当日结算参数的引导性提示而非报错；输出含生效区间/来源/置信度等 12 个字段，可选 parameter: "印花税" 子串过滤）

参考 demos/mcp_query_demo.py：它通过 MCP 调用多个工具，读取生成的 CSV，计算归一化价格，并绘制对比图。

python demos/mcp_query_demo.py

输出：

• demos/outputs/*.csv：各资产原始行情

• demos/outputs/normalized_returns.png：归一化走势图

• demos/outputs/summary.csv：汇总表

配置

项目根目录的 config.yaml：

providers:
  yahoo:
    # 默认使用 akshare。设为 true 则默认使用 yfinance。
    use_yfinance: false
cache:
  # download 批量下载的缓存根目录（默认 ./datasource-cache）。
  # 仅 download CLI 使用；MCP 查询不读写缓存。
  data_dir: ./datasource-cache

cache.data_dir 只影响 local-datasource download（见上文"批量下载"）；清单顶层 data_dir 与 CLI --data-dir 都比它优先。

也可通过环境变量指定配置文件：

LOCAL_DATASOURCE_CONFIG=/path/to/config.yaml local-datasource

扩展新数据源

src/local_datasource/providers/ 下的每个文件都是一个独立适配器，新增数据源的步骤：

1. 在 providers/ 新增一个 Python 文件，实现 query_xxx(...) 函数，返回 tuple[str, str]（文件路径 + 预览文本）。

2. 在 server.py 新增一个 @mcp.tool(structured_output=False) 薄工具函数：参数注解（Annotated/Literal/Field）即客户端可见 schema，docstring 即工具描述；函数体一行转发 _safe_summary。

3. 在 _summary_for() 中增加对应路由分支。

4. 更新 SKILL.md 和 README.md 的 tool 说明。

测试

测试随仓库分发（tests/ 目录）。离线单测不连网；联网冒烟默认开启，设 SKIP_INTEGRATION=1 跳过：

python -m pytest tests/ -v              # 全量(含联网冒烟)
SKIP_INTEGRATION=1 python -m pytest tests/ -q   # 仅离线

包含配置加载、格式化、缓存与 CLI、15 个 provider 的测试、MCP server 工具注册（16 个 tool）。

网络环境已知风险

以下为在本机实测（2026-09）确认的数据源网络情况，也是本轮海外数据源选型的依据（CBOE、纽约联储直连可达）：

• 东财非 A 股端点部分网络被拒：东财的全球指数/期货 K 线等非 A 股端点在部分网络环境下不可达（A 股相关端点不受影响）。美元指数已内置 Yahoo 自动回退。

• 金十美联储决议源 2025-09 起停更：美联储利率已改用纽约联储官方 EFFR API（免 key 直连）。

• FRED / treasury.gov / stooq 在本机实测不可用：美债收益率走东财全表（1990 起，短端走新浪），VIX 走 CBOE 官方 CSV 直连，不依赖上述源。

注意事项

• 分钟数据深度有限（免费源天花板）：期货分钟约 4 个交易日，腾讯源（个股/指数/ETF）约 8 个交易日。请求区间超出覆盖时会明确报错并提示从 Wind/终端导出 Excel 补数，不会静默返回残缺数据。

• 慢源与已知限制：中证系列指数日线走中证官网（约 10 秒，无分钟）；ETF 日线无复权（原始价）；期权仅日线。期货主连日线为全历史：自品种上市日（或 2005-01-04，取较早）至今，共 83 个主连品种（IF0 特例仅自 2017-01-17 起）。

• query_bond(kind=issue_info) 走中国货币网直连（akshare 未适配其改版）：站点按 IP 限窗口内请求数，单次查询约 75 秒（30 个债券类型节流遍历）；触发限流（HTTP 421）时自动退避 4 分钟重试一次，仍限流则如实报错。同一发行人的重复查询建议走 download 缓存。

• yfinance 容易被 Yahoo Finance 限流，因此默认优先使用 akshare。

• akshare 的接口可能随时间变化，建议定期更新到较新版本。

• World Bank 和 arXiv 通常稳定且无需 API key。

与 kimi-datasource 的异同

本项目的设计思路是：把常见的免费/公开数据查询能力做成一个本地、透明、可扩展的 MCP 服务。它并不复制 kimi-datasource 的具体实现（其接口实现并不公开），而是基于公开库重新组合出一套可用的本地替代方案。