用途

ashare-mcp 把中国 A 股（沪深京）财报变成 LLM 可调用的工具。用户用一句“平安银行 2024 年报怎么样？”就能让 Claude 或任何 MCP 客户端直接拿到结构化的资产负债表、利润表、现金流量表。数据来自东方财富，通过 akshare 获取，全部免费、无需 token。项目定位很窄：只做 A 股财报这一件事，做到任何 LLM 客户端十秒接入；它不预测股价、不写研报、不替用户做决策，只把数据以字段干净、单位清楚、错误明确的形式搬进 LLM 的工具调用里。

主要能力

三大报表获取

通过 get_three_statements 类工具获取结构化三大表，字段名保留东方财富原始英文（如 TOTAL_ASSETS / LOAN_ADVANCE / NETPROFIT），LLM 可直接理解，且银行、工商企业、保险等不同行业字段在同一份字典里，无需做行业判断。代码归一化支持 000001 / SZ000001 / sz.000001 / 000001.SZ 等多种格式。进程内 lru 缓存让同一公司多年份对比几乎零成本：冷启动一次拉全量，后续年份切换小于 1ms。

勾稽校验（cross_check_balance）

当前包含 4 条勾稽，前 3 条行业通用，第 4 条行业感知：

资产负债平衡：TOTAL_ASSETS = TOTAL_LIABILITIES + TOTAL_EQUITY
现金流恒等式：NETCASH_OPERATE + NETCASH_INVEST + NETCASH_FINANCE + RATE_CHANGE_EFFECT = CCE_ADD
期末/期初现金对账：END_CCE − BEGIN_CCE = CCE_ADD
营业利润分解（行业感知）：
- 银行：OPERATE_PROFIT = OPERATE_INCOME − OPERATE_EXPENSE
- 工商企业：OPERATE_PROFIT = TOTAL_OPERATE_INCOME − TOTAL_OPERATE_COST + OTHER_INCOME + INVEST_INCOME + FAIRVALUE_CHANGE_INCOME + ASSET_IMPAIRMENT_INCOME + CREDIT_IMPAIRMENT_INCOME + ASSET_DISPOSAL_INCOME [+ EXCHANGE_INCOME]
- 行业自动识别：有 ACCEPT_DEPOSIT > 10 亿走银行公式；有 TOTAL_OPERATE_INCOME + TOTAL_OPERATE_COST 走工商公式；否则 skipped（保险等暂不支持）。容忍度：前 3 条 1 万元（单项舍入），第 4 条 1000 万元（多项加总舍入累积）。字段缺失或行业无法识别时该条 skipped，不影响其它校验。据资料，实测 3 行业（银行 / 白酒 / 电池）4 家公司 2024 年报全过 4/4。走 lru cache 联动：先调 get_three_statements 后调 cross_check_balance，后者小于 1ms 秒回（同一只股票数据已在内存）。

同业对比（compare_peers）

默认指标：TOTAL_ASSETS / TOTAL_OPERATE_INCOME / PARENT_NETPROFIT / NETCASH_OPERATE / TOTAL_EQUITY，自动派生 ROE = PARENT_NETPROFIT / 平均权益（本年期末权益与去年期末权益的均值；去年数据走 lru cache 几乎无成本，缺失时降级为期末权益，并在 roe_method 字段标注 ending_equity_fallback）。自动 fallback：银行业 TOTAL_OPERATE_INCOME 缺失时退到 OPERATE_INCOME 并在 fallbacks 字段标注。并发实现使用 ThreadPoolExecutor(max_workers=8)，N 家公司并行拉取，单家失败不挂整体并记入 errors。据资料，实测 4 大银行 2024 年报对比约 38s 跑完；招行 ROE 12.85%。

使用方式

接入 Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（Mac），重启 Claude Desktop 后即可直接提问，例如：帮我看一下平安银行 2024 年报，总资产、总负债、净利润、经营性现金流分别多少？

HTTP API

除 MCP stdio 协议外，项目提供 FastAPI HTTP wrapper，供 Web 前端、curl、Postman 等任意 HTTP 客户端调用，共 5 个 endpoint（完整 schema 见 /docs 自动生成的 OpenAPI 页面）。错误统一格式：{"error": "...", "code": "INVALID_INPUT" | "UPSTREAM_ERROR"}（HTTP 422 / 502）。CORS 默认 *，生产部署前应收紧到具体域名；/api/compare-peers 单次最多 20 个代码（防请求放大），公开部署建议在反向代理层（Nginx / Cloudflare 等）再加限流。

Web 前端

web/ 子目录是 React + Vite + TypeScript + Tailwind 写的 4-tab 前端，直接调 HTTP API，4 个 tab 对应 4 个核心工具：三大报表 / 勾稽校验 / 同业对比 / 历史趋势。需要后端 ashare-mcp-http 同时跑在 :8000。详见 web/README.md。

可选文档解析

parse_document 工具用 opendatalab/MinerU 把 PDF / DOCX / PPTX / 图片（招股书、研报、年报扫描件等）解析成 LLM-ready 的 markdown。由于 MinerU pipeline 后端需要 torch + transformers 等数 GB 依赖，单独走 extra 安装：pip install -e ".[dev,pdf]"。不装也不影响其它 4 个工具，只是调用 parse_document 时会以 RuntimeError("mineru not installed") 友好失败。

部署与 CI

仓库内置三份部署配置，前后端分开部署：

后端（Railway）：连接仓库后自动读 nixpacks.toml 构建（锁 Python 3.11，不装 [pdf] extra），$PORT 由平台注入（见 http_app.py），健康检查打 /healthz。
前端（Vercel）：框架识别为 Vite，构建 web/ 子目录输出到 web/dist；部署前在 Vercel 环境变量里设置 VITE_API_BASE 指向后端地址。
.github/workflows/ci.yml 跑两个 job：Backend matrix（Python 3.10 / 3.11 / 3.12，pip install -e ".[dev]" 加 pytest tests/ -v 并验证 MCP 与 HTTP 入口可 import）；Frontend（Node 20，cd web && npm ci && tsc --noEmit && npm run build）。PDF 路径默认 skip，本地跑需 pip install -e ".[dev,pdf]" && pytest tests/test_parse_document.py -v。

适用场景

让 LLM 客户端直接查询 A 股公司年报三大表数据。
对财报做行业感知的会计勾稽校验。
对同业公司做指标对比与平均权益 ROE 计算。
通过 HTTP API 或内置 Web 前端让非技术用户试用。

限制

数据源为东方财富（通过 akshare），数据延迟、口径、准确性以东方财富为准，不构成投资建议。
保险等行业暂不支持营业利润分解勾稽，无法识别行业时该条 skipped。
parse_document 需要额外安装数 GB 依赖，默认不启用。
CORS 默认 *，公开部署需自行收紧并加限流。
项目不预测股价、不写研报、不做决策。
采用 MIT 许可，详见 LICENSE。

其他

日志走 stderr，不污染 MCP stdio 协议通道。未在资料中提供的安装时间、性能基准细节、具体收费信息等，暂未提供。

ashare-mcp

工具介绍

用途