akshare-mcp

MCP (Model Context Protocol) Server for AKShare Financial Data

Overview • Quick Start • Tools • Usage • Development • Architecture

---

Overview

akshare-mcp wraps AKShare — an open-source Chinese financial data library with 1000+ data functions — as a Model Context Protocol (MCP) server, enabling LLMs (Claude, etc.) to query Chinese financial data through standardized tool interfaces.

What you can query

Category	Examples
Stocks	Real-time quotes, historical bars, financial statements, board/industry indices, fund flow, margin trading, IPO data, LHB
Macroeconomics	GDP, CPI, PMI, money supply, interest rates — China, US, EU, Japan, etc.
Futures	Real-time/daily bars, settlement prices, open interest, warehouse receipts, basis analysis
Funds	Mutual fund NAV, ETF quotes & holdings, fund manager info, performance rankings
Bonds	Convertible bonds, treasury yields, corporate bonds, repo rates, NAFMII data
Options	CFFEX index options, SSE/SZSE ETF options, commodity options, Greeks, margin
Forex & Commodities	Exchange rates, gold/silver spot, crude oil, carbon emissions, hog prices
Indices	CSI/Shenwan/global indices, industry indices, index constituents
Alternative Data	Weather, news sentiment, migration, box office, wealth rankings, game rankings

---

Quick Start

Installation

pip install akshare-mcp

Note: AKShare requires Python ≥ 3.10 and uses the numpy, pandas, and requests packages. These will be installed automatically.

Usage

Run the server:

akshare-mcp

You should see:

[akshare-mcp] Loaded 13 tools covering 1086 akshare functions

Integrating with Claude Desktop

Add to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "akshare": {
      "command": "uvx",
      "args": ["akshare-mcp"]
    }
  }
}

If uvx is not available, use pip directly:

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

Integration with other MCP clients

Any MCP-compatible client can connect via stdio. The server listens on stdin/stdout and responds to the standard list_tools / call_tool requests.

---

Tools

akshare-mcp groups its 1000+ data functions into 13 category tools plus a discovery tool:

Category Tools

Tool	Functions	Category	Key Data
akshare_stock_a	226	A股行情	Real-time/historical quotes, IPO, LHB, technical indicators, market summaries
akshare_stock_fundamental	56	A股基本面	Financial statements, profit forecasts, ESG ratings, shareholders, dividends
akshare_stock_hk_us	36	港股美股	HK/US stock profiles, financials, quotes, exchange info
akshare_stock_board_flow	38	板块/资金流向	Concept & industry board indices, constituents, capital flow, north/south-bound connect
akshare_stock_margin_other	40	融资融券/其他	Margin trading, block trades, stock pledging, suspension/resumption, chip distribution
akshare_macro	225	宏观经济	China macro (GDP, CPI, PMI, M2, etc.), global macro (US, EU, JP, UK, AU, etc.)
akshare_futures	91	期货	Futures quotes, holdings, warehouse receipts, settlement, COT reports
akshare_fund	88	基金	Fund NAV, ETF quotes, manager profiles, performance rankings, AMAC stats
akshare_bond	46	债券	Convertible bonds, treasury yields, corporate bonds, repo, NAFMII
akshare_index	91	指数	CSI/Shenwan/global indices, sector analysis, index constituents
akshare_option	46	期权	Index/ETF/commodity options, Greeks, margin, option chains
akshare_fx_commodity	40	外汇/商品	Forex rates, energy, spot commodities, carbon emissions, crypto
akshare_other	63	其他数据	Air quality, movies, games, news, wealth rankings, QDII, REITs

Discovery Tool

Tool	Purpose
akshare_discover	Search functions by keyword across all categories

Common Tool Parameters

Every category tool accepts the same parameter interface:

Parameter	Type	Required	Description
method	str	Yes	The exact akshare function name to call (e.g. stock_zh_a_hist)
params_json	str	No	JSON-encoded keyword arguments for the function (default: "{}")
symbol	str	No	Convenience shortcut; forwarded as keyword argument
start_date	str	No	Convenience shortcut (format: YYYYMMDD)
end_date	str	No	Convenience shortcut (format: YYYYMMDD)
period	str	No	Convenience shortcut (e.g. daily, weekly, monthly)
adjust	str	No	Convenience shortcut for stock price adjustment (qfq, hfq)
date	str	No	Convenience shortcut for single-date parameters

Tip: Use akshare_discover first to find the right method name, then call the parent tool with method=function_name.

---

Usage Examples

Query real-time A-share stock quotes

# Via akshare_discover:
#   query="spot_em" → found in akshare_stock_a
# Then:
call_tool("akshare_stock_a", {
  "method": "stock_zh_a_spot_em"
})

Query historical stock data

call_tool("akshare_stock_a", {
  "method": "stock_zh_a_hist",
  "symbol": "300693",
  "period": "daily",
  "start_date": "20250101",
  "end_date": "20250708"
})

Query macroeconomic GDP data

call_tool("akshare_macro", {
  "method": "macro_china_gdp_yearly"
})

Search for a function

call_tool("akshare_discover", {
  "query": "gdp"
})
# Returns matching functions grouped by tool

Convertible bond market

call_tool("akshare_bond", {
  "method": "bond_zh_hs_cov_spot"
})

Fund flow by stock

call_tool("akshare_stock_board_flow", {
  "method": "stock_fund_flow_individual",
  "symbol": "300693"
})

---

Development

Setup

git clone https://github.com/xiaozhozho/akshare-mcp.git
cd akshare-mcp
pip install -e ".[dev]"

Run tests

python -m pytest tests/ -v

51 tests covering:

• DataFrame serialization (NaN/NaT/inf handling, datetime conversion, truncation)
• CategoryDispatcher (function dispatch, parameter merging, error wrapping)
• Error handling (akshare exception hierarchy, decorator pattern)
• ToolRegistry (auto-discovery, function assignment, cross-tool search)

Project structure

akshare-mcp/
├── pyproject.toml              # Build config (hatchling)
├── src/
│   └── akshare_mcp/
│       ├── server.py           # FastMCP entry point
│       ├── tools/
│       │   ├── base.py         # CategoryDispatcher base class
│       │   └── registry.py     # ToolRegistry + auto discovery
│       └── utils/
│           ├── dataframe.py    # DataFrame → JSON serialization
│           └── errors.py       # Error handling & wrapping
└── tests/                      # 51 pytest tests

How it works

1. Auto-discovery: ToolRegistry scans all public akshare callables at import time using inspect.getfile(), determines each function's source module, and assigns it to the appropriate category tool
2. Dispatch: Each category tool accepts a method parameter. The dispatcher resolves the function, merges convenience params with JSON params, calls akshare via asyncio.to_thread(), and serializes the resulting DataFrame
3. Error handling: All akshare exceptions (NetworkError, RateLimitError, InvalidParameterError, etc.) are caught and returned as structured error dicts — never raw exceptions
4. Serialization: DataFrames are converted to JSON with column metadata, row count, truncation handling, and proper NaN/NaT/inf → null conversion

Configuration

Environment Variable	Default	Description
AKSHARE_MCP_MAX_ROWS	500	Maximum rows returned per response

---

Architecture

┌─────────────────────────────────────────────────┐
│                   MCP Client                     │
│           (Claude Desktop, etc.)                 │
└──────────────┬──────────────────────┬────────────┘
               │  list_tools          │  call_tool
               ▼                      ▼
┌─────────────────────────────────────────────────┐
│              FastMCP (stdio transport)           │
├─────────────────────────────────────────────────┤
│  ToolRegistry (13 category dispatchers)          │
│  ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
│  │ stock_a  │ │ macro    │ │ discover         │ │
│  │ 226 funcs│ │ 225 funcs│ │ search + index    │ │
│  └──────────┘ └──────────┘ └──────────────────┘ │
├─────────────────────────────────────────────────┤
│  CategoryDispatcher                              │
│  ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
│  │ method → │ │ params →  │ │ asyncio.to_thread│ │
│  │ func     │ │ merge     │ │ → akshare call   │ │
│  └──────────┘ └──────────┘ └──────────────────┘ │
├─────────────────────────────────────────────────┤
│  Utils                                            │
│  ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
│  │dataframe │ │ errors   │ │ akshare library  │ │
│  │serialize │ │ wrap     │ │ ~1086 functions  │ │
│  └──────────┘ └──────────┘ └──────────────────┘ │
└─────────────────────────────────────────────────┘

---

License

Apache License 2.0

See LICENSE for the full license text.

---

Related Projects

• AKShare — The underlying financial data library
• AKTools — HTTP API wrapper for AKShare
• MCP Python SDK — The MCP framework used