Skip to main content
Glama
sciciv

akshare-mcp

by sciciv
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

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': {...}}

ParametersJSON Schema
NameRequiredDescriptionDefault
symbolYes
periodNoannual

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It describes the return dict structure, includes error handling, notes currency (CNY), and explains period options. No mention of auth or rate limits, but sufficient for a read-only tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with Args, Returns, Example sections. Front-loaded with purpose. Slightly verbose but still concise enough.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema existing, the description still provides detailed return info, error handling, and parameter guidance. Complete for a tool of this complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so description compensates fully. It explains symbol as a 6-digit A-share code with example, and period as 'annual' (default) or 'quarterly'. Adds meaning beyond the schema types.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Get key financial-statement line items for an A-share company.' It specifies the resource (financial statements) and scope (A-share), and it distinguishes itself from siblings like get_industry_news and get_stock_quote.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains when to use each parameter, including default behavior for period. It provides an example. It does not explicitly state when not to use, but the sibling context makes the usage clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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': '...'}, ...]}

ParametersJSON Schema
NameRequiredDescriptionDefault
industryYes
daysNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, but the description fully covers behavior: look-back window capped at 30 days, default 7, dropping older items, return structure (with count, articles), and error handling (error key on failure).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with Args, Returns, Example sections. Every sentence adds value. Front-loaded with purpose. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity and the detailed description including output shape and error handling, it is complete. The presence of an output schema (implied by description) reduces need for further detail.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but description adds rich meaning: industry must be in Chinese, days is a look-back window with default 7 and cap 30. All parameters are explained beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clear verb 'Get' and resource 'news headlines for an industry or theme'. It naturally distinguishes from sibling tools (financial statements, stock quote) which are about financial data.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides example and clarifies parameter constraints, but does not explicitly state when to use this tool over siblings. However, the context implies differentiation by domain.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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, ...}

ParametersJSON Schema
NameRequiredDescriptionDefault
symbolYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations so description carries full burden. Describes successful return (dict with price, change, volume, etc.) and failure case (error key). Does not explicitly state read-only or idempotent, but behavior is clear.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with Args, Returns, and Example sections. Every sentence adds value, though slightly verbose with docstring conventions.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Complete for a simple tool: describes input, output, error handling, and provides example. No annotations needed; description covers all relevant aspects.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 0% coverage; description fully compensates with format ('6-digit A-share code'), examples ('600519', '300750'), and context. Adds meaning beyond type alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states 'Get the real-time quote for a single A-share stock' with specific verb and resource. Distinguishes from siblings (get_financial_statements, get_industry_news) by focusing on quotes vs financials vs news.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides example and explains parameter format. Implicitly distinguishes from siblings via purpose. Lacks explicit when-not-to-use or alternative guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 3 tool updatesv0.1.0
    • First observedget_financial_statements
    • First observedget_industry_news
    • First observedget_stock_quote
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

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 issues

Resources

Related MCP Connectors

Related MCP Servers