Skip to main content
Glama
akshare-mcp

akshare-mcp

by sciciv

akshare-mcp

An MCP server that gives AI assistants direct, structured access to China A-share market data.

CI License: Apache 2.0 Python PyPI MCP

一句话:让 Claude、Coze、豆包等 AI 助手,通过标准 MCP 协议直接读取 A 股行情、 财报与行业新闻。


What is this?

akshare-mcp wraps the excellent open-source AKShare data library behind the Model Context Protocol (MCP) — the open standard for connecting AI assistants to tools and data. Once connected, an AI host can answer questions like "What's Kweichow Moutai's latest annual net profit?" or "Any photovoltaics news this week?" by calling typed tools instead of guessing.

It is the open-source data-access module of 司南 (SciCiv) — a project building a China-localized counterpart to Anthropic's Claude for Financial Services (CFS). Where CFS connects Claude to Western market data providers, SciCiv focuses on bringing the same agentic, tool-using workflows to China's A-share market — and this module is the first, fully open piece of that.

Related MCP server: akshare-one-mcp

Features

Three tools ship in v0.1:

Tool

What it returns

get_stock_quote(symbol)

Real-time quote: latest price, change %, volume, turnover, P/E, P/B, total & float market cap.

get_financial_statements(symbol, period="annual")

Key line items from the income statement, balance sheet, and cash-flow statement (annual or quarterly).

get_industry_news(industry, days=7)

Recent news headlines for an industry/theme keyword (title, source, time, link).

All tools return clean JSON, cache upstream calls (see Architecture), and degrade to a friendly {"error": ...} envelope on failure rather than crashing the connection.

Quick Start

30 seconds to your first tool call.

# 1. Install (Python 3.10+)
git clone https://github.com/gavin3129/akshare-mcp.git
cd akshare-mcp
pip install -e .

# 2. Try the tools directly against live data
python examples/demo.py            # quote + financials + news for 600519 / 光伏

Connect it to Claude Desktop:

  1. Find your Python path: which python (use the env where you just installed).

  2. Add this to Claude Desktop's config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

    {
      "mcpServers": {
        "akshare": {
          "command": "/absolute/path/to/python",
          "args": ["-m", "akshare_mcp.server"]
        }
      }
    }
  3. Restart Claude Desktop, then ask: "What's the latest quote for 600519?"

See examples/ for the full config and walkthrough.

Architecture

   You ──"茅台最新财报?"──▶  AI Host  ──MCP (stdio/JSON-RPC)──▶  akshare-mcp ──▶ AKShare ──▶ Eastmoney
                        (Claude/Coze/豆包)                      (this repo)              (live data)
                              ▲                                      │
                              └──────────── clean JSON ◀─────────────┘

The server is a thin adapter: it turns a model's tool call into an AKShare function call, caches and normalizes the result, and returns clean JSON. Tool functions are plain Python (no MCP imports), so they're independently testable and reusable.

Highlights (full rationale in docs/architecture.md):

  • Per-dataset TTL caching — quotes 60 s, news 10 min, financials 1 day. The quote tool caches the whole-market snapshot, so screening many tickers costs one network call, not one per ticker.

  • Errors as data — every tool is wrapped so failures become structured envelopes an AI agent can reason about, never stack traces.

  • Schema from type hints — FastMCP derives each tool's JSON schema from its annotations and docstring, so there's no second contract to maintain.

Roadmap

Version

Focus

v0.1 (current)

3 core tools: quote, financials, news. stdio transport. Offline-tested.

v0.2 (planned)

More tools: index/sector data, fund flows, dividend history, shareholder structure. Batch quote tool.

v0.3 (planned)

HTTP/SSE transport for remote hosting; optional Redis-backed cache; rate-limit handling; English field localization layer.

Scope is kept deliberately tight per version to stay reliable and reviewable.

License & Acknowledgments

Licensed under the Apache License 2.0.

This project stands on the shoulders of:

  • AKShare — the open-source financial-data library that does the heavy lifting of sourcing A-share data. Please consider starring and supporting the upstream project.

  • Anthropic — for the Model Context Protocol and for Claude for Financial Services, which inspired the SciCiv initiative.

Author

Gavin Meng · 司南 / SciCiv (科学公民) — building China-localized, open agentic finance tooling.

Available Tools

3 tools
get_financial_statementsA

Get key financial-statement line items for an A-share company.

Args: symbol: A 6-digit A-share code, e.g. "600519". period: "annual" for the latest fiscal-year report (default), or "quarterly" for the most recent quarterly report.

Returns: A dict with the latest income_statement, balance_sheet and cash_flow key items (values in CNY), plus the report_date they were drawn from. On failure, a dict with an error key.

Example: >>> get_financial_statements("600519", "annual") # doctest: +SKIP {'symbol': '600519', 'period': 'annual', 'report_date': '2023-12-31', 'income_statement': {'total_revenue': 1.5e11, 'net_profit': 7.4e10, ...}, 'balance_sheet': {...}, 'cash_flow': {...}}

Inputs: symbol (required), period. Returns: object

get_industry_newsA

Get recent news headlines for an industry or theme.

Args: industry: An industry/theme keyword in Chinese, e.g. "光伏" (photovoltaics) or "新能源车" (electric vehicles). days: Look-back window in days (default 7, capped at 30). Items older than this are dropped.

Returns: A dict with the query echoed back and an articles list, each item carrying title, source, published_at and url. On failure, a dict with an error key.

Example: >>> get_industry_news("光伏", days=7) # doctest: +SKIP {'industry': '光伏', 'days': 7, 'count': 12, 'articles': [{'title': '...', 'source': '...', 'published_at': '2024-01-15 10:30:00', 'url': '...'}, ...]}

Inputs: industry (required), days. Returns: object

get_stock_quoteA

Get the real-time quote for a single A-share stock.

Args: symbol: A 6-digit A-share code, e.g. "600519" (Kweichow Moutai) or "300750" (CATL).

Returns: A dict with the latest price, change percentage, volume, turnover and market-cap figures. On failure, a dict with an error key explaining what went wrong.

Example: >>> get_stock_quote("600519") # doctest: +SKIP {'symbol': '600519', 'name': '贵州茅台', 'price': 1683.0, 'change_pct': 0.85, 'volume': 31250, 'total_market_cap': 2.1e12, ...}

Inputs: symbol (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.5/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool targets a clearly distinct data type: financial statements, industry news, and real-time quotes. There is no overlap in purpose or output structure.

    Naming Consistency5/5

    All three tools follow a consistent get_verb_noun naming pattern with lowercase and underscores. No mixed conventions.

    Tool Count4/5

    Three tools is a small set but covers essential financial data queries. Could be slightly expanded, but the count is reasonable for a focused utility.

    Completeness3/5

    The set covers core data retrieval (quotes, statements, news) but lacks symbol search, historical data, or sector classification, leaving notable gaps for basic workflows.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers