English | 简体中文

ashare-mcp

An MCP server built on baostock that exposes all 23 baostock data endpoints as MCP tools: K-line, quarterly financials (profit / operation / growth / balance / cash-flow / DuPont), performance express & forecast reports, dividends, adjust factors, industry classification, index constituents, the trading calendar, and macro series.

It also ships two disclosure-announcement (公告) tools backed by EastMoney's public HTTP APIs — list announcements for a stock and download the PDF — since baostock has no announcement surface. EastMoney's endpoints are reachable outside mainland China, so these work even when baostock's data port is blocked.

The data layer sits behind a DataProvider abstraction. v1 ships the baostock backend, with the seam in place to add other sources later without touching the tool layer. The announcement tools live alongside the provider (they don't go through baostock at all).

Install

uv sync

Related MCP server: sfc-data-mcp

Run (stdio)

uv run ashare-mcp

Configure it in a stdio MCP client (Claude Desktop / Claude Code / Cursor):

{
  "mcpServers": {
    "ashare": {
      "command": "uv",
      "args": ["--directory", "/path/to/ashare-mcp", "run", "ashare-mcp"]
    }
  }
}

Tools

Every baostock-backed data tool returns a uniform shape: {"count": int, "fields": [...], "data": [{...}, ...]}. The announcement tools return their own shape (see below).

Disclosure announcements (公告)

Two EastMoney-backed tools, independent of baostock:

• get_stock_announcements(code, start_date="", end_date="", page_size=50, keyword="") — list a stock's announcements newest-first. code accepts sh.600519 / sz.002049 / 600519. start_date / end_date are inclusive YYYY-MM-DD filters. keyword is a case-sensitive substring on the title (e.g. 重组). Returns {code, count, data:[{art_code, title, notice_date, type, pdf_url_guess}]}.

• download_stock_announcement(art_code, save_dir="") — download the announcement PDF by the art_code returned above. Resolves the real attachment URL via EastMoney's content API (falls back to the H2_<art_code>_1.pdf convention if needed). Returns {art_code, title, save_dir, files:[{path, url, bytes}]} — open the returned path with the MCP client's file/Read tool to read the PDF.

Typical flow: call get_stock_announcements → pick an art_code → download_stock_announcement → read the saved PDF.

Codes

Pass baostock-form codes: sh.600519, sz.000001, bj.430047. Bare 6-digit codes (e.g. 600519) are normalized best-effort, but ambiguous index codes (e.g. 000001 is both SSE Composite sh.000001 and Ping An Bank sz.000001) should be passed with an explicit prefix.

Configuration

Development

uv run pytest -q              # unit tests (no network)
uv run pytest -q -m network   # live baostock smoke test

Notes

• baostock's data port must be reachable from your network (reachable inside mainland China; may time out elsewhere). If baostock tools start timing out, check this first. The EastMoney announcement tools use a separate HTTPS endpoint and are typically reachable outside CN.

• baostock needs no registration, but each process still must call bs.login() to open a session — this server logs in once and logs out on shutdown.

• The announcement tools are stdlib-only (no new dependencies) and run off the baostock session, so they keep working even if baostock is down.