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, andrequestspackages. 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_discoverfirst to find the rightmethodname, then call the parent tool withmethod=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
- Auto-discovery:
ToolRegistryscans all public akshare callables at import time usinginspect.getfile(), determines each function's source module, and assigns it to the appropriate category tool - Dispatch: Each category tool accepts a
methodparameter. The dispatcher resolves the function, merges convenience params with JSON params, calls akshare viaasyncio.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.
Related Projects
- AKShare — The underlying financial data library
- AKTools — HTTP API wrapper for AKShare
- MCP Python SDK — The MCP framework used
Metadata
Release files for akshare-mcp-service 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| akshare_mcp_service-0.1.0.tar.gz | 31.3 kB | Without provenance | Details for akshare_mcp_service-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| akshare_mcp_service-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for akshare_mcp_service-0.1.0-py3-none-any.whl |
Total release size: 56.2 kB
Security for akshare-mcp-service 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.