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

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

pip install agentladle-mcp-akshare

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

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

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

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 }

# 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: []

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

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."

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."

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.

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."

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