local-datasource

Local Datasource

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

---

一句话介绍

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

---

为什么需要这个项目

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

• 查一只股票过去一年的走势
• 对比黄金、美股、A股等多资产表现
• 拉取某个国家的 GDP/CPI 数据
• 检索某个领域的 arXiv 论文

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

• 数据请求不出本机：适合对合规、隐私敏感的场景。
• 无需账号和额度：基于公开接口，安装完就能用。
• 标准 MCP 协议：不绑定任何特定 Agent，可被多家产品复用。
• 源码可见、可扩展：增加新数据源或调整输出格式都很直接。

---

核心特点

• ✅ A股 / 港股 / 美股：日线行情，支持前复权/后复权。
• ✅ 美股 / ETF / 全球资产：默认 akshare 美股接口，可回退 yfinance。
• ✅ 世界银行宏观指标：GDP、CPI、人口等。
• ✅ arXiv 论文搜索：标题、作者、摘要、PDF 链接结构化输出。
• ✅ 中国境内债券：国债收益率曲线、信用债发行信息（按代码或发行人查）、交易所行情。
• ✅ 可转债：一览含溢价率、强赎/回售条款、历史K线、发行人正股财务报表。
• ✅ 金融输入归一化：股票/债券的名称、简称、全称、发行人 → 统一代码（resolve_stock_code + bond_issue）。
• ✅ 统一 CSV 输出：每个 tool 都把结果写到 file_path，并返回前 5 行预览。
• ✅ 零 API Key：所有默认数据源均免费使用。
• ✅ 跨 Agent 复用：标准 MCP Server，配置一条 command 即可接入。

---

适用人群

• 需要在 Agent 工作流里频繁查数据的投研、分析师、开发者。
• 不希望把查询请求发送到云端的本地优先用户。
• 想学习/定制 MCP 数据服务器实现的开发者。

---

快速开始

# 1. 克隆并安装
pip install -e .

# 2. 启动 MCP 服务
local-datasource

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

---

覆盖范围

| 数据类型 | 工具 | 底层接口 | 是否需 API Key | |---|---|---|---| | A股 / 港股 / 美股 历史行情 | query_stock | akshare | 否 | | 美股 / ETF / 全球资产 | query_yfinance | akshare（默认）/ yfinance（备选） | 否 | | 世界银行宏观指标 | query_worldbank | wbgapi | 否 | | arXiv 学术论文 | query_arxiv | arxiv | 否 | | 中国境内债券（国债收益率曲线/信用债发行信息/交易所行情） | query_bond | akshare | 否 | | 可转债（一览/条款/历史K线/发行人财务） | query_convertible_bond | akshare | 否 | | 股票名称（简称/全称）→ 代码候选 | resolve_stock_code | 新浪 suggest API / akshare | 否 |

---

金融输入归一化

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

• 股票：公司简称/全称 → 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, ...)

城投/非上市发行人无上市股票，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                       # 项目介绍（本文档）
├── pyproject.toml                  # Python 包配置与依赖
├── config.yaml                     # 可选配置文件
├── src/local_datasource/           # MCP server 源码
│   ├── server.py                   # 服务入口：注册 tools、处理调用
│   ├── config.py                   # 加载 config.yaml / 环境变量
│   ├── formatters.py               # 统一 CSV 输出与预览
│   └── providers/                  # 各数据源适配器
│       ├── stock.py                # A/HK/US 股票 + resolve_stock_code 名称反查
│       ├── yahoo.py                # 美股/全球资产
│       ├── worldbank.py            # 世界银行
│       ├── arxiv.py                # arXiv 论文
│       ├── bond.py                 # 中国境内债券（国债收益率/信用债发行/交易所行情）
│       └── convertible_bond.py     # 可转债（一览/条款/历史K线/发行人财务）
└── 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）

---

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

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

---

注意事项

• yfinance 容易被 Yahoo Finance 限流，因此默认优先使用 akshare。
• akshare 的接口可能随时间变化，建议定期更新到较新版本。
• World Bank 和 arXiv 通常稳定且无需 API key。

---

与 kimi-datasource 的异同

| 维度 | local-datasource | kimi-datasource | |---|---|---| | 运行位置 | 本机 | Kimi Code 云端 | | 登录/账号 | 不需要 | 需要 Kimi Code 账号 | | 费用 | 免费（受公开接口限额影响） | 消耗 Kimi Code 额度 | | 数据源 | A/HK/US 股票、美股/ETF、World Bank、arXiv | 更多，包括天眼查、Google Scholar、元典法律等 | | 数据链路 | Agent → 本地 Server → 公开接口 | Agent → Kimi 云服务 → 后端数据源 | | 可定制性 | 源码本地可见，可修改/扩展 | 黑盒，只能使用官方暴露的 tool | | 跨 Agent 复用 | 标准 MCP Server，可被多家 Agent 复用 | 仅限 Kimi Code 内部 |

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