agentladle-mcp-akshare

AgentLadle MCP AKShare

English | 中文

🇨🇳 China A-Share Market — Cloud-hosted MCP for annual financial reports (2023-2025). Read more | Get API Key

A MCP (Model Context Protocol) server that provides 46 financial data tools for AI assistants, covering A-share, HK, US markets, macroeconomics, funds, and derivatives — powered by AKShare.

It enables AI assistants (Claude, Cursor, etc.) to access financial market data through 46 semantic tools — from candlestick history to macro indicators, with unified symbol format, normalized output, and built-in caching/rate-limiting.

Features

• 46 MCP tools across 11 scopes: market, quote, flow, fundamentals, shareholders, content, sector, sentiment, IPO, macro, derivatives
• Unified symbol format: <code>.<market> (e.g. 000001.SZ, 00700.HK, AAPL.US) — automatically converted to each AKShare function's required format
• Normalized output: Chinese column names → English snake_case with unit conversion (万元→元, 亿股→股)
• Built-in infrastructure: TTL cache (history 24h / realtime 10s), token-bucket rate limiter (10 QPS global), retry with fallback sources, asyncio.to_thread async wrapping
• outputSchema: Each tool returns a typed ToolResponse dataclass with structured output schema
• Tool annotations: readOnlyHint, idempotentHint, openWorldHint on all tools
• Scope-based loading: Load a subset of tools via AKSHARE_MCP_SCOPES env var (e.g. market,quote)
• AI workflow hints: Each response includes a hint field guiding the next logical step
• Chinese keyword handling: AKShare's Chinese enum parameters (e.g. 北向资金) mapped to English (direction=north)
• Zero-config install — one line to add to your MCP client, no clone or manual setup needed
• Pure Python, cross-platform (Windows / macOS / Linux)

Prerequisites

• Python 3.10+ — Download Python
• uv — Install uv

Note: After installing uv, restart your terminal and MCP client (e.g. Claude Desktop, Cursor) to ensure the uv command is recognized.

Quick Start

Add to your MCP client configuration (Claude Desktop, Cursor, etc.):

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

That's it. uvx will automatically download the package and its dependencies from PyPI — no clone, no manual install, no path configuration.

Optional: Scope filtering

To load only specific scopes (useful for clients with tool count limits):

{
  "mcpServers": {
    "mcp-akshare": {
      "command": "uvx",
      "args": ["agentladle-mcp-akshare"],
      "env": {
        "AKSHARE_MCP_SCOPES": "market,quote,fundamentals"
      }
    }
  }
}

Alternative: pip install

If you prefer managing the environment yourself:

pip install agentladle-mcp-akshare

Then configure:

{
  "mcpServers": {
    "mcp-akshare": {
      "command": "agentladle-mcp-akshare"
    }
  }
}

Alternative: Run from source (local development)

Clone the repository and run directly:

git clone https://github.com/agentladle/mcp-akshare.git

Then configure your MCP client:

{
  "mcpServers": {
    "mcp-akshare": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-akshare", "agentladle-mcp-akshare"]
    }
  }
}

Replace /path/to/mcp-akshare with the actual path to the cloned repository.

Data Flow

AKShare Library (1.18.40)           MCP AKShare Server
──────────────────────              ──────────────────────────────────
stock_zh_a_hist()          ──→     get_candlesticks()
stock_zh_a_spot_em()       ──→     get_quote()
stock_financial_*()        ──→     get_financial_statement/metrics()
stock_hsgt_hist_em()       ──→     get_northbound_flow()
stock_zt_pool_em()         ──→     get_limit_up_pool()
macro_china_gdp()          ──→     get_macro_data()
fund_etf_hist_em()         ──→     get_fund_nav_history()
                                    │
                                    ├── Symbol Normalizer (<code>.<market> → func-specific format)
                                    ├── Param Normalizer (period/adjust/date/keyword enums)
                                    ├── Field Mapper (中文列名 → English snake_case + unit conversion)
                                    ├── TTL Cache (history 24h / realtime 10s / fundamental 1h)
                                    ├── Rate Limiter (10 QPS global, 2 QPS per-interface)
                                    └── Retry + Fallback (primary → backup source)
                                    │
                                    ▼
                              ToolResponse { status, data, hint, cached, source, updated_at }

Tools

46 tools across 11 scopes. All tools are read-only with readOnlyHint=true.

Scope: market (4 tools)

Tool 1: get_trading_days

Get trading days for a market between dates.

Tool 2: get_market_status

Get current trading status for all markets (CN/HK/US). No parameters.

Tool 3: get_security_list

List securities for a market.

Tool 4: get_exchange_rate

Get major currency exchange rates.

Scope: quote (5 tools)

Tool 5: get_candlesticks

Get candlestick (OHLCV) data for any asset class — routes to the correct AKShare function based on asset_class × period.

Tool 6: get_quote

Get latest quote snapshot for one or more symbols.

Tool 7: get_intraday

Get intraday time-share data.

Tool 8: get_depth

Get order book (bid/ask depth).

Tool 9: get_trades

Get recent trade ticks.

Scope: flow (4 tools)

Tool 10: get_capital_flow

Get capital flow time series for a stock.

Tool 11: get_northbound_flow

Get northbound/southbound capital flow (Stock Connect).

Tool 12: get_margin_trading

Get margin trading data (financing + short selling).

Tool 13: get_block_trade

Get block trade (大宗交易) records.

Scope: fundamentals (8 tools)

Scope: shareholders (5 tools)

Scope: content (4 tools)

Scope: sector (4 tools)

Scope: sentiment (6 tools)

Scope: ipo (2 tools)

Scope: macro (4 tools)

Scope: derivatives (8 tools)

*Tools 47-49 cover fund data within the derivatives scope.

Configuration

On first run, a default config file is created at ~/.agentladle/mcp-akshare/config.yaml:

# MCP AKShare Server Configuration
cache:
  ttl_history: 86400       # 24h — historical daily data
  ttl_realtime: 10          # 10s — real-time quotes
  ttl_fundamental: 3600     # 1h — financial statements
  ttl_calendar: 604800      # 7d — trading calendar
  ttl_company: 86400        # 1d — company basic info
  ttl_news: 300             # 5m — news
  max_size: 200             # max cached entries

ratelimit:
  global_qps: 10            # global 10 QPS
  per_interface_qps: 2      # per-interface 2 QPS

retry:
  max_retries: 1
  timeout: 30.0
  retry_delay: 1.0

# Comma-separated scope list (empty = all scopes)
# Available: market,quote,flow,fundamentals,shareholders,content,sector,sentiment,ipo,macro,derivatives
scopes: []

Environment Variables

Configuration can be overridden via environment variables (highest priority):

Data Directory Structure

~/.agentladle/mcp-akshare/
├── config.yaml                        # Configuration (auto-created)
└── data/                              # Data directory

Example Usage

The tools are designed with an EAFP (Easier to Ask for Forgiveness than Permission) approach. AI assistants should directly invoke data retrieval tools and rely on the hint field for workflow guidance.

Scenario A: Get stock price history

User: "What's Apple's stock price trend over the last 30 days?"

1. get_candlesticks(symbol="AAPL.US", period="day", count=30)
   → Returns 30 daily OHLCV bars.
   → hint: "Use get_quote for real-time price, or get_financial_metrics for fundamentals."

Scenario B: Fundamental analysis workflow

User: "Analyze Ping An Bank's fundamentals"

1. get_company(symbol="000001.SZ")
   → Returns company overview (industry, listing date, shares).

2. get_financial_metrics(symbol="000001.SZ", count=8)
   → Returns ROE, ROA, margins, debt ratio for 8 periods.

3. get_valuation(symbol="000001.SZ")
   → Returns current PE, PB, PS, dividend yield.
   → hint: "Use get_valuation_history for PE/PB trend."

Scenario C: Discover valid symbols

User: "What stocks are in the CSI 300 index?"

1. get_index_constituent(symbol="000300.INDEX")
   → Returns 300 constituent stocks with weights.

2. get_candlesticks(symbol="600519.SH", count=10)
   → Get candlestick data for a specific constituent.

Scenario D: Market sentiment

User: "How's the A-share market doing today?"

1. get_market_summary(market="CN")
   → Returns up/down/flat counts, limit-up/down counts, total turnover.

2. get_limit_up_pool()
   → Returns today's limit-up stocks with reasons.
   → hint: "Check consecutive_days for multi-day limit-ups."

Tech Stack

Project Structure

src/akshare_mcp/
├── __init__.py                # Package version
├── __main__.py               # python -m entry point
├── server.py                 # FastMCP init + tool registration + logging (stderr)
├── config.py                 # Config loading (~/.agentladle/mcp-akshare/config.yaml, singleton)
├── instances.py              # Service singletons (lazy-loaded)
├── models.py                 # Internal data models (dataclass)
├── response.py               # Response builders (success/error/skipped + hint)
├── scopes.py                 # 11 scope definitions + tool mapping
├── tools/                    # Tool layer (thin: parameter validation + response wrapping)
│   ├── market.py             #   scope: market (4 tools)
│   ├── quote.py              #   scope: quote (5 tools)
│   ├── flow.py               #   scope: flow (4 tools)
│   ├── fundamental.py        #   scope: fundamentals (8 tools)
│   ├── shareholder.py        #   scope: shareholders (5 tools)
│   ├── news.py               #   scope: content (4 tools)
│   ├── sector.py             #   scope: sector (4 tools)
│   ├── sentiment.py          #   scope: sentiment (6 tools)
│   ├── ipo.py                #   scope: ipo (2 tools)
│   ├── macro.py              #   scope: macro (4 tools)
│   └── derivative.py         #   scope: derivatives (8 tools)
├── services/                 # Business layer (thick: core logic)
│   ├── base_service.py       #   Base class with config/retry accessors
│   ├── market_service.py     #   Trading days, candlesticks, quotes, depth
│   ├── fundamental_service.py # Financials, valuation, shareholders, IPO
│   ├── flow_service.py       # Capital flow, northbound, margin, block trade
│   ├── news_service.py       # News, filings, research reports
│   ├── sentiment_service.py  # Limit pools, dragon tiger, anomaly, summary
│   ├── macro_service.py      # Macro indicators, interest rates, bond yields
│   ├── sector_service.py     # Index constituents, sector quotes/rank
│   ├── fund_service.py       # Fund quote, NAV, holdings
│   ├── derivative_service.py # Futures, options, bonds, forex, REITs
│   ├── symbol_normalizer.py  # Unified <code>.<market> → function-specific format
│   ├── param_normalizer.py   # Period/adjust/date/keyword enum mapping
│   └── field_mapper.py       # Chinese column → English snake_case + unit conversion
├── output/                   # OutputSchema types (Longbridge-style)
│   ├── common.py             #   ToolResponse wrapper
│   ├── market.py             #   TradingDayItem, SecurityItem, ...
│   ├── quote.py              #   CandlestickItem, QuoteItem, DepthOutput, ...
│   ├── flow.py               #   CapitalFlowItem, NorthboundFlowItem, ...
│   ├── fundamental.py        #   CompanyInfo, FinancialMetricItem, ValuationData, ...
│   ├── shareholder.py        #   ShareholderItem, InsiderTradeItem, ...
│   ├── content.py            #   NewsItem, FilingItem, ResearchReportItem
│   ├── sector.py             #   IndexConstituentItem, SectorQuoteItem, ...
│   ├── sentiment.py          #   LimitPoolItem, DragonTigerItem, MarketSummary, ...
│   ├── ipo.py                #   IPOCalendarItem, IPODetail
│   ├── macro.py              #   MacroIndicatorItem, InterestRateItem, ...
│   └── derivatives.py        #   FundQuoteItem, FuturesQuoteItem, OptionQuoteItem, ...
└── infra/                    # Infrastructure
    ├── cache.py              #   TTL cache with LRU eviction
    ├── ratelimit.py          #   Token bucket (global + per-interface)
    ├── retry.py              #   Retry with exponential backoff
    └── async_wrap.py         #   asyncio.to_thread wrapper for sync calls

License

MIT