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

# 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

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
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
Error handling: All akshare exceptions (NetworkError, RateLimitError, InvalidParameterError, etc.) are caught and returned as structured error dicts — never raw exceptions
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.

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

akshare-mcp

Overview

What you can query

Quick Start

Installation

Usage

Integrating with Claude Desktop

Integration with other MCP clients

Tools

Category Tools

Discovery Tool

Common Tool Parameters

Usage Examples

Query historical stock data

Query macroeconomic GDP data

Search for a function

Convertible bond market

Fund flow by stock

Development

Setup

Run tests

Project structure

How it works

Configuration

Architecture

License

Latest Blog Posts

MCP directory API

Overview

What you can query

Quick Start

Installation

Usage

Integrating with Claude Desktop

Integration with other MCP clients

Tools

Category Tools

Discovery Tool

Common Tool Parameters

Usage Examples

Query real-time A-share stock quotes

Query historical stock data

Query macroeconomic GDP data

Search for a function

Convertible bond market

Fund flow by stock

Development

Setup

Run tests

Project structure

How it works

Configuration

Architecture

License

Related Projects

Latest Blog Posts

MCP directory API