Local Datasource

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

一句话介绍

local-datasource 把 akshare、yfinance、wbgapi、arxiv 等免费公开接口封装成 11 个标准 MCP tool，Agent 只需要像调用本地函数一样请求数据，即可获得结构化 CSV 输出。

Related MCP server: MCP Financial Data Gateway

为什么需要这个项目

在日常投研、尽调、学术检索或自动化报告生成中，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)，与日线同一入口。

• ✅ 金融输入归一化：股票/债券的名称、简称、全称、发行人 → 统一代码（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
        ↓ 原始数据源
新浪 / 腾讯 / 交易所官网 / 中证指数 / 同花顺 / 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、处理调用
│   ├── config.py                   # 加载 config.yaml / 环境变量
│   ├── formatters.py               # 统一 CSV 输出与预览
│   └── 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/股指：月份/清单/日线）
└── 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

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

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"）

参考 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

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

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

扩展新数据源

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

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

2. 在 server.py 的 build_tools() 中注册新 tool。

3. 在 handle_call_tool() 中增加路由。

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

测试

测试文件位于本地 tests/ 目录（未提交到 GitHub）：

python -m pytest tests/ -v

包含配置加载、格式化、10 个 provider 的集成测试、MCP server 工具注册（11 个 tool）。

注意事项

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

• 慢源与已知限制：中证系列指数日线走中证官网（约 10 秒，无分钟）；期货主连仅约 158 日；ETF 日线无复权（原始价）；期权仅日线。

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

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

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

与 kimi-datasource 的异同

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