Skip to main content
Glama
xiaozhozho

akshare-mcp

by xiaozhozho
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

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

Related MCP server: sfc-data-mcp

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

Install Server
A
license - permissive license
B
quality
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

View all tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/xiaozhozho/akshare-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server