akshare-mcp

An MCP server that gives AI assistants direct, structured access to China A-share market data.

一句话：让 Claude、Coze、豆包等 AI 助手，通过标准 MCP 协议直接读取 A 股行情、 财报与行业新闻。

---

What is this?

akshare-mcp wraps the excellent open-source AKShare data library behind the Model Context Protocol (MCP) — the open standard for connecting AI assistants to tools and data. Once connected, an AI host can answer questions like "What's Kweichow Moutai's latest annual net profit?" or "Any photovoltaics news this week?" by calling typed tools instead of guessing.

It is the open-source data-access module of 司南 (SciCiv) — a project building a China-localized counterpart to Anthropic's Claude for Financial Services (CFS). Where CFS connects Claude to Western market data providers, SciCiv focuses on bringing the same agentic, tool-using workflows to China's A-share market — and this module is the first, fully open piece of that.

Features

Three tools ship in v0.1:

Tool	What it returns
get_stock_quote(symbol)	Real-time quote: latest price, change %, volume, turnover, P/E, P/B, total & float market cap.
get_financial_statements(symbol, period="annual")	Key line items from the income statement, balance sheet, and cash-flow statement (annual or quarterly).
get_industry_news(industry, days=7)	Recent news headlines for an industry/theme keyword (title, source, time, link).

All tools return clean JSON, cache upstream calls (see Architecture), and degrade to a friendly {"error": ...} envelope on failure rather than crashing the connection.

Quick Start

30 seconds to your first tool call.

# 1. Install (Python 3.10+)
git clone https://github.com/gavin3129/akshare-mcp.git
cd akshare-mcp
pip install -e .

# 2. Try the tools directly against live data
python examples/demo.py            # quote + financials + news for 600519 / 光伏

Connect it to Claude Desktop:

1. Find your Python path: which python (use the env where you just installed).

2. Add this to Claude Desktop's config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

   {
     "mcpServers": {
       "akshare": {
         "command": "/absolute/path/to/python",
         "args": ["-m", "akshare_mcp.server"]
       }
     }
   }
   

3. Restart Claude Desktop, then ask: "What's the latest quote for 600519?"

See examples/ for the full config and walkthrough.

Architecture

   You ──"茅台最新财报?"──▶  AI Host  ──MCP (stdio/JSON-RPC)──▶  akshare-mcp ──▶ AKShare ──▶ Eastmoney
                        (Claude/Coze/豆包)                      (this repo)              (live data)
                              ▲                                      │
                              └──────────── clean JSON ◀─────────────┘

The server is a thin adapter: it turns a model's tool call into an AKShare function call, caches and normalizes the result, and returns clean JSON. Tool functions are plain Python (no MCP imports), so they're independently testable and reusable.

Highlights (full rationale in docs/architecture.md):

• Per-dataset TTL caching — quotes 60 s, news 10 min, financials 1 day. The quote tool caches the whole-market snapshot, so screening many tickers costs one network call, not one per ticker.
• Errors as data — every tool is wrapped so failures become structured envelopes an AI agent can reason about, never stack traces.
• Schema from type hints — FastMCP derives each tool's JSON schema from its annotations and docstring, so there's no second contract to maintain.

Roadmap

Version	Focus
v0.1 (current)	3 core tools: quote, financials, news. stdio transport. Offline-tested.
v0.2 (planned)	More tools: index/sector data, fund flows, dividend history, shareholder structure. Batch quote tool.
v0.3 (planned)	HTTP/SSE transport for remote hosting; optional Redis-backed cache; rate-limit handling; English field localization layer.

Scope is kept deliberately tight per version to stay reliable and reviewable.

License & Acknowledgments

Licensed under the Apache License 2.0.

This project stands on the shoulders of:

• AKShare — the open-source financial-data library that does the heavy lifting of sourcing A-share data. Please consider starring and supporting the upstream project.
• Anthropic — for the Model Context Protocol and for Claude for Financial Services, which inspired the SciCiv initiative.

Author

Gavin Meng · 司南 / SciCiv (科学公民) — building China-localized, open agentic finance tooling.

• GitHub: gavin3129/akshare-mcp
• Contributions, issues, and ideas are welcome.