akshare-mcp
Enables Coze AI agents to retrieve structured A-share market data including stock quotes, financial statements, and industry news through the MCP interface.
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.
Related MCP server: akshare-one-mcp
Features
Three tools ship in v0.1:
Tool | What it returns |
| Real-time quote: latest price, change %, volume, turnover, P/E, P/B, total & float market cap. |
| Key line items from the income statement, balance sheet, and cash-flow statement (annual or quarterly). |
| 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:
Find your Python path:
which python(use the env where you just installed).Add this to Claude Desktop's config (
~/Library/Application Support/Claude/claude_desktop_config.jsonon macOS,%APPDATA%\Claude\claude_desktop_config.jsonon Windows):{ "mcpServers": { "akshare": { "command": "/absolute/path/to/python", "args": ["-m", "akshare_mcp.server"] } } }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.
Available Tools
3 toolsget_financial_statementsA
Get key financial-statement line items for an A-share company.
Args:
symbol: A 6-digit A-share code, e.g. "600519".
period: "annual" for the latest fiscal-year report (default), or
"quarterly" for the most recent quarterly report.
Returns:
A dict with the latest income_statement, balance_sheet and
cash_flow key items (values in CNY), plus the report_date they
were drawn from. On failure, a dict with an error key.
Example: >>> get_financial_statements("600519", "annual") # doctest: +SKIP {'symbol': '600519', 'period': 'annual', 'report_date': '2023-12-31', 'income_statement': {'total_revenue': 1.5e11, 'net_profit': 7.4e10, ...}, 'balance_sheet': {...}, 'cash_flow': {...}}
Inputs: symbol (required), period. Returns: object
get_industry_newsA
Get recent news headlines for an industry or theme.
Args:
industry: An industry/theme keyword in Chinese, e.g. "光伏"
(photovoltaics) or "新能源车" (electric vehicles).
days: Look-back window in days (default 7, capped at 30). Items older
than this are dropped.
Returns:
A dict with the query echoed back and an articles list, each item
carrying title, source, published_at and url. On
failure, a dict with an error key.
Example: >>> get_industry_news("光伏", days=7) # doctest: +SKIP {'industry': '光伏', 'days': 7, 'count': 12, 'articles': [{'title': '...', 'source': '...', 'published_at': '2024-01-15 10:30:00', 'url': '...'}, ...]}
Inputs: industry (required), days. Returns: object
get_stock_quoteA
Get the real-time quote for a single A-share stock.
Args:
symbol: A 6-digit A-share code, e.g. "600519" (Kweichow Moutai) or
"300750" (CATL).
Returns:
A dict with the latest price, change percentage, volume, turnover and
market-cap figures. On failure, a dict with an error key explaining
what went wrong.
Example: >>> get_stock_quote("600519") # doctest: +SKIP {'symbol': '600519', 'name': '贵州茅台', 'price': 1683.0, 'change_pct': 0.85, 'volume': 31250, 'total_market_cap': 2.1e12, ...}
Inputs: symbol (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool targets a clearly distinct data type: financial statements, industry news, and real-time quotes. There is no overlap in purpose or output structure.
All three tools follow a consistent get_verb_noun naming pattern with lowercase and underscores. No mixed conventions.
Three tools is a small set but covers essential financial data queries. Could be slightly expanded, but the count is reasonable for a focused utility.
The set covers core data retrieval (quotes, statements, news) but lacks symbol search, historical data, or sector classification, leaving notable gaps for basic workflows.
Maintenance
Related MCP Connectors
China A-share market data for research, backtesting and AI agents via MCP.
MCP server for real-time China A-share stock quotes, indices and market data.
China A-share & equity research MCP server (回声投研) for market quotes, filings, financials, fund flows, concepts & sentiment.
Trading MCP server for AI agents, with live market data, account reads and controlled execution.
Related MCP Servers
- AlicenseBqualityDmaintenanceMCP server that provides AI assistants access to stock market data including financial statements, stock prices, and market news through a Model Context Protocol interface.112,324MIT
- AlicenseAqualityBmaintenanceMCP server that provides access to Chinese stock market data using akshare-one9585 PyPI247MIT
- AlicenseNot gradedqualityDmaintenanceA MCP server that provides HTTP-based access to Tushare financial data, enabling AI assistants to query stocks, indices, funds, and more.2MIT
- FlicenseNot gradedqualityDmaintenanceMCP server for A-share stock technical analysis and AI prediction, enabling LLM-based interaction to analyze stocks.345-