# akshare-mcp

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

[![CI](https://github.com/gavin3129/akshare-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/gavin3129/akshare-mcp/actions/workflows/test.yml)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](./LICENSE)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
[![PyPI](https://img.shields.io/badge/PyPI-coming%20soon-blue.svg)](https://pypi.org/project/akshare-mcp/)
[![MCP](https://img.shields.io/badge/protocol-MCP-7c3aed.svg)](https://modelcontextprotocol.io)

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

---

## What is this?

`akshare-mcp` wraps the excellent open-source [AKShare](https://akshare.akfamily.xyz/)
data library behind the [Model Context Protocol (MCP)](https://modelcontextprotocol.io) —
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.

## 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](#architecture)),
and degrade to a friendly `{"error": ...}` envelope on failure rather than
crashing the connection.

## Quick Start

**30 seconds to your first tool call.**

```bash
# 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):

   ```json
   {
     "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/`](./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`](./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](./LICENSE).

This project stands on the shoulders of:

- **[AKShare](https://akshare.akfamily.xyz/)** — 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](https://www.anthropic.com/)** — 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.

- GitHub: [gavin3129/akshare-mcp](https://github.com/gavin3129/akshare-mcp)
- Contributions, issues, and ideas are welcome.