ashare-mcp

Purpose

ashare-mcp turns Chinese A-share (Shanghai/Shenzhen/Beijing) financial reports into tools callable by LLMs. With a single sentence such as "How was Ping An Bank's 2024 annual report?", users can let Claude or any MCP client directly obtain structured balance sheets, income statements, and cash flow statements. The data comes from East Money and is retrieved via akshare; it is entirely free and requires no token. The project's positioning is very narrow: it does only one thing, A-share financial reports, and makes it achievable for any LLM client to integrate in ten seconds; it does not predict stock prices, write research reports, or make decisions for users. It only moves data into LLM tool calls in a form with clean fields, clear units, and explicit errors.

Main capabilities

Retrieval of the three major statements

Structured three major statements are obtained through tools such as get_three_statements. Field names retain East Money's original English (such as TOTAL_ASSETS / LOAN_ADVANCE / NETPROFIT), which LLMs can understand directly, and fields for different industries such as banks, industrial and commercial enterprises, and insurance are in the same dictionary, so no industry judgment is needed. Code normalization supports multiple formats such as 000001 / SZ000001 / sz.000001 / 000001.SZ. The in-process lru cache makes multi-year comparison for the same company almost zero-cost: one cold start pulls the full dataset, and subsequent year switching takes less than 1ms.

Cross-check validation (cross_check_balance)

Currently includes 4 cross-checks. The first 3 are common across industries, and the 4th is industry-aware:

1. Balance sheet balance: TOTAL_ASSETS = TOTAL_LIABILITIES + TOTAL_EQUITY
2. Cash flow identity: NETCASH_OPERATE + NETCASH_INVEST + NETCASH_FINANCE + RATE_CHANGE_EFFECT = CCE_ADD
3. Ending/beginning cash reconciliation: END_CCE − BEGIN_CCE = CCE_ADD
4. Operating profit decomposition (industry-aware):
   • Banks: OPERATE_PROFIT = OPERATE_INCOME − OPERATE_EXPENSE
   • Industrial and commercial enterprises: 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 are present, use the industrial and commercial formula; otherwise skipped (insurance and others are not currently supported). Tolerance: the first 3 checks use 10,000 yuan (rounding of a single item), and the 4th uses 10 million yuan (accumulated rounding from summing multiple items). When fields are missing or the industry cannot be identified, that check is skipped and does not affect other checks. According to the materials, in actual testing 4 companies across 3 industries (bank / baijiu / battery) all passed 4/4 for their 2024 annual reports. Linked with lru cache: if get_three_statements is called first and then cross_check_balance, the latter responds in less than 1ms (the same stock's data is already in memory).

Peer comparison (compare_peers)

Default metrics: TOTAL_ASSETS / TOTAL_OPERATE_INCOME / PARENT_NETPROFIT / NETCASH_OPERATE / TOTAL_EQUITY, with automatically derived ROE = PARENT_NETPROFIT / average equity (the average of the current year's ending equity and last year's ending equity; last year's data goes through lru cache at almost no cost, and when missing it degrades to ending equity and is marked in the roe_method field as ending_equity_fallback). Automatic fallback: for the banking industry, when TOTAL_OPERATE_INCOME is missing, it falls back to OPERATE_INCOME and marks this in the fallbacks field. The concurrent implementation uses ThreadPoolExecutor(max_workers=8), pulling N companies in parallel; failure of a single company does not crash the whole operation and is recorded in errors. According to the materials, in actual testing the comparison of the 2024 annual reports of the 4 major banks took about 3Completes in 8s; China Merchants Bank ROE 12.85%.

Usage

Connecting to Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (Mac), restart Claude Desktop and you can ask questions directly, for example: Take a look at Ping An Bank's 2024 annual report for me, what are total assets, total liabilities, net profit, and operating cash flow respectively?

HTTP API

In addition to the MCP stdio protocol, the project provides a FastAPI HTTP wrapper for any HTTP client such as web frontends, curl, Postman, etc., with 5 endpoints in total (for the complete schema see the auto-generated OpenAPI page at /docs). Unified error format: {"error": "...", "code": "INVALID_INPUT" | "UPSTREAM_ERROR"} (HTTP 422 / 502). CORS defaults to *, and should be tightened to specific domains before production deployment; /api/compare-peers accepts at most 20 codes per request (to prevent request amplification), and for public deployment it is recommended to add rate limiting at the reverse proxy layer (Nginx / Cloudflare, etc.).

Web Frontend

The web/ subdirectory is a 4-tab frontend written in React + Vite + TypeScript + Tailwind, calling the HTTP API directly; the 4 tabs correspond to the 4 core tools: three major statements / cross-check validation / peer comparison / historical trends. The backend ashare-mcp-http needs to be running on :8000 at the same time. See web/README.md for details.

Optional Document Parsing

The parse_document tool uses opendatalab/MinerU to parse PDF / DOCX / PPTX / images (prospectuses, research reports, scanned annual reports, etc.) into LLM-ready markdown. Since the MinerU pipeline backend requires several GB of dependencies such as torch + transformers, install it separately via an extra: pip install -e ".[dev,pdf]". Not installing it does not affect the other 4 tools; it just fails gracefully with RuntimeError("mineru not installed") when parse_document is called.

Deployment and CI

The repository includes three deployment configurations, with frontend and backend deployed separately:

• Backend (Railway): after connecting the repository it automatically reads nixpacks.toml to build (pins Python 3.11, does not install the [pdf] extra), $PORT is injected by the platform (see http_app.py), and the health check hits /healthz.
• Frontend (Vercel): the framework is detected as Vite, builds the web/ subdirectory and outputs to web/dist; before deployment set VITE_API_BASE in the Vercel environment variables to point to the backend address.
• .github/workflows/ci.yml runs two jobs: Backend matrix (Python 3.10 / 3.11 / 3.12, pip install -e ".[dev]" plus pytest tests/ -v and verifies that the MCP and HTTP entry points can be imported); Frontend (Node 20, cd web && npm ci && tsc --noEmit && npm run build). The PDF path is skipped by default; to run it locally you need pip install -e ".[dev,pdf]" && pytest tests/test_parse_document.py -v.

Applicable Scenarios

• Let LLM clients directly query the three major statements data from A-share company annual reports.
• Perform industry-aware accounting cross-check validation on financial reports.
• Perform metric comparison and average equity ROE calculation for peer companies.
• Let non-technical users try it out via the HTTP API or the built-in web frontend.

Limitations

• The data source is East Money (via akshare); data latency, definitions, and accuracy are subject to East Money, and this does not constitute investment advice.
• Industries such as insurance do not currently support operating profit decomposition cross-check validation; when the industry cannot be identified, that item is skipped.
• parse_document requires installing several GB of additional dependencies and is not enabled by default.
• CORS defaults to *, and publicdeployment requires tightening it yourself and adding rate limiting.
• The project does not predict stock prices, write research reports, or make decisions.
• Licensed under MIT, see LICENSE for details.

Other

Logs go to stderr and do not pollute the MCP stdio protocol channel. Installation time, performance benchmark details, specific pricing information, etc. not provided in the materials are not yet available.