ashare-mcp

Turn A-share financial reports into tools your LLM can call. An MCP server that turns Chinese A-share financial statements into tools your LLM can call.

Let Claude (or any MCP client) get structured balance sheets, income statements, and cash flow statements with a single prompt like "How was Ping An Bank's 2024 annual report?" Fields are curated, units are clear, and it is cache-friendly.

Data sourced from East Money via akshare, completely free, no token required.

Why build another one?

Most "Financial LLM" projects on GitHub are crowded in trading agents and SEC 10-K RAG—the former is highly homogenized, and the latter only serves US stocks. The combination of A-shares + Chinese + MCP protocol layer is almost a blank space.

ashare-mcp has a very narrow focus: do one thing—A-share financial reports—and do it well enough to be integrated into any LLM client in ten seconds. It doesn't predict stock prices, write research reports, or make decisions for you—it simply moves data from East Money into LLM tool calls, with clean fields, clear units, and explicit error handling.

Related MCP server: ashare-mcp

Quick Start

git clone https://github.com/yli769227-jpg/ashare-mcp.git
cd ashare-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

Run a smoke test:

python -c "from ashare_mcp.data_source import get_annual_statements; \
  r = get_annual_statements('SZ000001', 2024); \
  print(r['company_name'], r['balance_sheet']['TOTAL_ASSETS'])"
# -> 平安银行 5769270000000.0

Integrate with Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (Mac):

{
  "mcpServers": {
    "ashare": {
      "command": "/absolute/path/to/ashare-mcp/.venv/bin/python",
      "args": ["-m", "ashare_mcp.server"]
    }
  }
}

Restart Claude Desktop, and you can ask directly:

Help me look at Ping An Bank's 2024 annual report. What are the total assets, total liabilities, net profit, and operating cash flow?

Tool List

Code normalization supports multiple formats: 000001 / SZ000001 / sz.000001 / 000001.SZ.

cross_check_balance currently includes 4 cross-checks (the first 3 are industry-agnostic, the 4th is industry-aware):

1. Balance Sheet Equilibrium — TOTAL_ASSETS = TOTAL_LIABILITIES + TOTAL_EQUITY

2. Cash Flow Identity — NETCASH_OPERATE + NETCASH_INVEST + NETCASH_FINANCE + RATE_CHANGE_EFFECT = CCE_ADD

3. End/Beginning Cash Reconciliation — END_CCE − BEGIN_CCE = CCE_ADD

4. Operating Profit Decomposition (Industry-Aware)

   • Banks: OPERATE_PROFIT = OPERATE_INCOME − OPERATE_EXPENSE

   • Industrial/Commercial: 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]

   • Automatic Industry Identification: If ACCEPT_DEPOSIT > 1 billion, use the bank formula; if TOTAL_OPERATE_INCOME + TOTAL_OPERATE_COST exist, use the industrial formula; otherwise skipped (insurance, etc., not yet supported).

Tolerance: 10,000 RMB for the first 3 (rounding of individual items), 10 million RMB for the 4th (cumulative rounding of multiple items). If fields are missing or the industry cannot be identified, the check is skipped, which does not affect other checks. Tested on 3 industries (banks / liquor / batteries) and 4 companies' 2024 annual reports, all passed 4/4.

Leverages LRU cache: Call get_three_statements first, then cross_check_balance, and the latter returns in < 1ms (data for the same stock is already in memory).

compare_peers default metrics: TOTAL_ASSETS / TOTAL_OPERATE_INCOME / PARENT_NETPROFIT / NETCASH_OPERATE / TOTAL_EQUITY, automatically derives ROE = PARENT_NETPROFIT / Average Equity (average of current year-end equity and last year-end equity; last year's data is retrieved via LRU cache at almost zero cost; if last year's data is missing, it falls back to year-end equity, marked in the roe_method field as ending_equity_fallback). Automatic fallback: For banks, if TOTAL_OPERATE_INCOME is missing, it falls back to OPERATE_INCOME and marks it in the fallbacks field. Concurrency implementation: ThreadPoolExecutor (max_workers=8), pulls data for N companies in parallel (failure of one does not crash the whole process, recorded in errors). Tested 4 major banks' 2024 annual reports in ~38s; China Merchants Bank ROE 12.85% (long-term leader in retail).

Architecture

flowchart LR
    LLM[Claude / 任意 MCP 客户端] -->|JSON-RPC over stdio| Server[ashare-mcp<br/>FastMCP server]
    Server -->|代码归一化| Norm[股票代码归一化<br/>SZ/SH/BJ 自动判断]
    Server -->|拉取三表| DS[数据源封装<br/>akshare 包装层]
    DS -->|缓存命中| Cache[(进程内存缓存<br/>lru_cache)]
    DS -->|缓存未命中| YearlyEM[akshare<br/>by_yearly_em]
    YearlyEM -->|HTTP| EM[东方财富<br/>财报数据接口]
    DS -->|字段过滤| Filter[剔除元数据列<br/>剔除同比列<br/>剔除空/零字段]
    Server -->|结构化 JSON| LLM

Key Design:

• Field names retain original East Money English (TOTAL_ASSETS / LOAN_ADVANCE / NETPROFIT). LLMs can understand them directly, and fields for different industries like banks / industrial / insurance are all in the same dictionary, requiring no industry judgment.

• In-process memory caching makes "multi-year comparison for the same company" almost zero-cost—cold start pulls the full volume, subsequent year switching is < 1ms.

• Logs go to stderr, not polluting the MCP stdio protocol channel.

Roadmap

Local Development

# 增量验证(每次改完跑一遍)
python -c "from ashare_mcp.utils import normalize_stock_code; \
  assert normalize_stock_code('000001') == 'SZ000001'"

python -c "from ashare_mcp.server import mcp; \
  import asyncio; print([t.name for t in asyncio.run(mcp.list_tools())])"

Data Disclaimer

• Data source: East Money, via akshare.

• Data latency, definitions, and accuracy are subject to East Money, and do not constitute investment advice.

• For educational and research purposes only.

License

MIT — see LICENSE.