A Share MCP

English | 简体中文

Source-labeled, agent-friendly Chinese A-share data tools exposed as a local stdio MCP server.

A Share MCP is designed for data retrieval and structured research inputs rather than trading automation. It helps AI agents retrieve A-share quotes, price history, financial indicators, business composition, announcements, and compact company data packs with explicit data-source metadata.

For research and education only. This project does not provide investment advice, trading signals, brokerage integration, or buy/sell recommendations.

Why this project

There are already broad financial-data MCP servers. This project intentionally stays lightweight and research-oriented:

• No token required for the MVP — uses public Eastmoney endpoints and AkShare wrappers.
• Source-labeled outputs — every tool returns source metadata for downstream audit and citation.
• Agent-friendly summaries — get_financial_summary and get_company_snapshot reduce noisy raw tables into useful research payloads.
• Local-first stdio MCP — easy to run in Claude Desktop, Hermes, Cursor, or any MCP client.
• Conservative by design — public data can be delayed or incomplete; important facts should be verified against official filings.

Tools

• a_share_healthcheck — Check AkShare / Eastmoney reachability.
• search_stock — Search A-share securities by Chinese name or code.
• get_stock_profile — Basic company profile.
• get_realtime_quote — Quote snapshot, valuation fields, market cap, industry.
• get_daily_history — Daily OHLCV history with none/qfq/hfq adjustment options.
• get_financial_indicators — Raw financial indicator table.
• get_financial_summary — Compact core financial metrics for agents.
• get_business_composition — Business / revenue composition table.
• search_announcements — CNINFO / Eastmoney announcement search with normalized IDs, detail URLs, and PDF URLs.
• get_announcement_detail — Normalize a CNINFO announcement detail link and optionally extract a bounded PDF text preview with quality metrics and OCR fallback.
• search_research_reports — Public broker research search for background reading.
• get_company_snapshot — One-call research pack: quote, profile, price stats, financial summary, business composition, and recent announcements.
• get_research_pack — Structured company data pack with price records, financials, business composition, announcements, optional broker research, and a source ledger.
• get_industry_peers — Same-industry A-share peers with valuation and market-cap fields.
• get_peer_comparison — Simple percentile comparison against same-industry peers.
• get_index_snapshot — Mainland China index quote snapshot.
• get_sector_snapshot — Industry/concept board snapshot list.
• get_sector_components — Component stocks for an industry/concept board.
• get_financial_events_pack — Dividend, repurchase, shareholder-change, financing, and restricted-release event pack.
• get_dividend_events / get_repurchase_events / get_shareholder_change_events / get_financing_events / get_restricted_release_events — Event-specific tools.
• get_announcement_layout — Best-effort PDF page layout extraction with OCR lines or embedded text blocks.
• batch_get_quotes — Batch quote snapshots with partial-failure isolation.
• batch_company_snapshot — Batch company snapshots.
• compare_companies — Compare selected companies by quote/valuation metrics.
• screen_stocks — Simple data screening by industry, market cap, and PE.
• get_market_overview — Major indices plus industry/concept board snapshots.
• get_financial_trends — Agent-friendly trend summary derived from financial indicators.
• classify_announcements — Keyword-based announcement category summary.
• get_cache_status / clear_cache — Inspect or clear the local JSON cache.

Install

git clone https://github.com/Kinneyzhang/a-share-mcp.git
cd a-share-mcp
python -m pip install -e .

Install with OCR extras when you want automatic PDF OCR fallback:

python -m pip install -e '.[ocr]'

Run the MCP server:

a-share-mcp

Or run from source:

python scripts/a_share_mcp_server.py

MCP client configuration

Use an absolute path for args when configuring desktop/agent clients.

mcp_servers:
  a_share:
    command: "python"
    args: ["/ABSOLUTE/PATH/TO/a-share-mcp/scripts/a_share_mcp_server.py"]
    timeout: 180
    connect_timeout: 60

If installed as a console script:

mcp_servers:
  a_share:
    command: "a-share-mcp"
    args: []
    timeout: 180
    connect_timeout: 60

Tool names are usually prefixed by your client, e.g. mcp_a_share_get_company_snapshot.

Smoke test

Deterministic protocol smoke test, suitable for CI:

python -m py_compile a_share_mcp/*.py scripts/*.py
python scripts/protocol_smoke.py

Optional live-data smoke test, useful before local releases:

python scripts/smoke_mcp.py

Live smoke output includes:

{
  "ok": true,
  "tools": 34,
  "quote_name": "贵州茅台"
}

Examples

Search by Chinese name:

{
  "tool": "search_stock",
  "arguments": {"keyword": "药明康德", "limit": 5}
}

Build a company research pack:

{
  "tool": "get_company_snapshot",
  "arguments": {"symbol": "603259", "history_days": 60, "announcement_limit": 5}
}

Build a structured data pack with source ledger:

{
  "tool": "get_research_pack",
  "arguments": {"symbol": "603259", "history_days": 120, "announcement_limit": 10, "include_reports": false}
}

Get normalized announcement metadata and PDF URL:

{
  "tool": "get_announcement_detail",
  "arguments": {
    "detail_url": "http://www.cninfo.com.cn/new/disclosure/detail?stockCode=603259&announcementId=1225278835&orgId=9900035584&announcementTime=2026-05-07%2000:00:00",
    "include_text": false,
    "text_mode": "auto"
  }
}

Get compact financial metrics:

{
  "tool": "get_financial_summary",
  "arguments": {"symbol": "600519", "start_year": "2024"}
}

More examples are in examples/prompts.md.

Cache

A small best-effort JSON cache is enabled by default:

• Default path: ~/.cache/a-share-mcp/
• Override path: A_SHARE_MCP_CACHE_DIR=/path/to/cache
• Disable most cache behavior by setting very small TTLs in code or clearing the directory.

Tool responses include a cache object when served through the cache wrapper. Use get_cache_status and clear_cache for operational inspection and cleanup.

Data sources

• Eastmoney public endpoints for quote and daily kline data.
• AkShare wrappers for A-share lists, financial indicators, business composition, CNINFO disclosure search, and research reports.

Limitations

• Public endpoints can change, throttle, or return delayed data.
• Quote data can be unavailable outside market windows; a zero intraday value should not be treated as a real zero price.
• Financial indicator fields are source-defined; always verify report period and accounting scope.
• Announcement text extraction is best-effort. In text_mode=auto, the server tries embedded PDF text first, then OCR fallback when the embedded text is empty or garbled. When text_status is poor_quality, treat text as unreliable and use pdf_url as the canonical source.
• Peer comparison tools are simple data summaries, not valuation judgments or investment ratings.
• This server does not execute trades, connect to broker accounts, or produce investment recommendations.

API stability

Starting with v1.0.0, tool names and existing argument names are treated as stable:

• Patch releases fix bugs and should not remove fields.
• Minor releases may add tools, optional arguments, or response fields.
• Breaking changes require a new major version and migration notes.

License

MIT