Content
# Tool List
<div align="center">
**Pure TypeScript Implementation of Chinese A-Share Market Data MCP Server**
[](https://opensource.org/licenses/MIT)
[](https://www.typescriptlang.org/)
[](https://nodejs.org/)
[](https://modelcontextprotocol.io/)
[](https://www.npmjs.com/package/ahshare-mcp)
</div>
---
## Overview
**ahshare-mcp** is a server based on [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) that provides Chinese A-share market financial data access capabilities for AI assistants such as Claude Desktop and VS Code Copilot.
**Core Features**: Compatible with Python version [akshare-one-mcp](https://github.com/zwldarren/akshare-one-mcp) functionality, but implemented in pure TypeScript with zero Python dependencies.
### Differences from Python Version
| Dimension | Python Version | TypeScript Version |
|------|-----------|---------------|
| Language | Python 3.12+ | **TypeScript 5.x** |
| Runtime | CPython | **Node.js 22+** |
| Data Source | Through `akshare-one` library | **Direct HTTP API Calls** |
| Python Dependencies | ❌ Required | ✅ Zero Dependencies |
| Technical Indicators | pandas calculations | **Pure TS Math Implementation** |
| Deployment | Python + pip/uv | **Single Node.js Process** |
| Image Size | ~500MB | **~150MB** |
| MCP Tools | 9 | **12** (including Shareholders/Fund Holdings) |
---
## Features
### 📊 Market Data (3 Tools)
- **Historical K-lines** — Daily/Weekly/Monthly/Minutely, support pre/post dividend adjustment, multiple data sources
- **Real-time Quotes** — Latest price, price change, market value, PE/PB
- **34 Technical Indicators** — SMA/EMA/MACD/RSI/BOLL/ATR/CCI/ADX/MFI etc.
### 💰 Financial Statements (4 Tools)
- **Balance Sheet** — Total assets, fixed assets, cash, inventory, liabilities
- **Income Statement** — Revenue, cost, operating profit, net profit
- **Cash Flow Statement** — Operating/investing/financing cash flows
- **Financial Metrics** — Key metrics from three statements
### 👥 Shareholder Data (3 Tools)
- **Top 10 Shareholders** — Ranking, shares held, proportion, changes
- **Top 10 Circulating Shareholders** — Type classification (fund/QFII/broker/insurance)
- **Fund Holdings** — **Full** (not limited to top 10), over 1000 records
### 📰 Others (2 Tools)
- **Stock News** — Oriental Fortune news search
- **Internal Trades** — Directors and supervisors' increase/decrease records
- **Time Information** — Current time + recent trading day
---
## Installation
### Prerequisites
- [Node.js](https://nodejs.org/) >= 22
- (Optional) [Bun](https://bun.sh/) for development
### Install via npm
```bash
npm install -g ahshare-mcp
```
### Install from Source
```bash
git clone https://github.com/terrysun1216/ahshare-mcp-ts.git
cd ahshare-mcp-ts
npm install
npm run build
```
---
## Usage
### Claude Desktop Integration
Add to Claude Desktop configuration file:
```json
{
"mcpServers": {
"ahshare-mcp": {
"command": "npx",
"args": ["ahshare-mcp"]
}
}
}
```
Or in VS Code Copilot:
```json
{
"mcpServers": {
"ahshare-mcp": {
"command": "npx",
"args": ["tsx", "/path/to/ahshare-mcp-ts/src/main.ts"]
}
}
}
```
### Command Line
```bash
# stdio mode (default, for MCP clients)
ahshare-mcp
# HTTP mode (for remote/web clients)
ahshare-mcp --streamable-http --port 8081
```
### Example Conversation
After configuration, you can have conversations like this in Claude:
> "Help me check the recent 30-day daily trend and MACD indicator of Guizhou茅台 600519"
> "Who are the top 10 shareholders of Guizhou茅台? What is their market value?"
> "Compare the PE, ROE and other financial indicators of 600519 and 000858"
> "Which funds are heavily holding Guizhou茅台?"
---
## MCP Tool List
| # | Tool Name | Description | Data Source |
|---|--------|------|--------|
| 1 | `get_time_info` | Current time, timestamp, recent trading day | Sina |
| 2 | `get_hist_data` | Historical K-line data + 34 technical indicators | Oriental Fortune/Sina |
| 3 | `get_realtime_data` | Real-time quotes (price/change/market value/PE/PB) | Oriental Fortune |
| 4 | `get_news_data` | Stock news | Oriental Fortune |
| 5 | `get_balance_sheet` | Balance sheet | Oriental Fortune |
| 6 | `get_income_statement` | Income statement | Oriental Fortune |
| 7 | `get_cash_flow` | Cash flow statement | Oriental Fortune |
| 8 | `get_financial_metrics` | Key metrics from three statements | Oriental Fortune |
| 9 | `get_inner_trade_data` | Directors and supervisors' internal trades | Xueqiu |
| 10 | `get_top10_shareholders` | Top 10 shareholders + top 10 circulating shareholders | Oriental Fortune F10 |
| 11 | `get_top10_free_shareholders` | Top 10 circulating shareholders details | Oriental Fortune F10 |
| 12 | `get_fund_holdings` | Fund holdings details (full) | Sina Finance |
### 34 Technical Indicators
| Category | Indicators |
|------|------|
| Trend | SMA, EMA, MACD, APO, PPO, TRIX, ULTOSC |
| Momentum | RSI, CCI, ADX, DX, MFI, MOM, CMO, WILLR |
| Volatility | BOLL, ATR, SAR |
| Volume | OBV, AD, ADOSC |
| Direction | PLUS_DI, PLUS_DM, MINUS_DI, MINUS_DM |
| Change Rate | ROC, ROCP, ROCR, ROCR100 |
| Others | AROON, AROONOSC, BOP, STOCH, TSF |
---
## Architecture
```
┌─────────────────────────┐
│ MCP Client │
│ (Claude Desktop / VS Code) │
└──────┬──────────────────┘
│ JSON-RPC (stdio / HTTP)
┌──────┴──────────────────┐
│ MCP Server Layer │
│ @modelcontextprotocol/ │
│ sdk + Hono + Zod │
├──────────────────────────┤
│ Service Layer │
│ Quotes / Finance / Shareholders / News │
├──────────────────────────┤
┌──────────┼──────────┬──────────────┤
│ │ │ │
┌────┴───┐ ┌───┴────┐ ┌───┴───┐ ┌───────┴──┐
│Oriental Fortune │ │ Sina │ │ Xueqiu │ │ Indicator Engine │
│ HTTP │ │ HTTP │ │ HTTP │ │ 34 Functions │
└────────┘ └────────┘ └───────┘ └──────────┘
```
**Data Flow**: MCP Client → JSON-RPC → MCP Server → Service → HTTP Provider → Oriental Fortune/Sina/Xueqiu Public API
**Zero Python Dependencies**: Directly call each data source's public HTTP interface from TypeScript, using Node.js built-in `fetch` API.
---
## Tech Stack
| Package | Version | Usage |
|----|------|------|
| `@modelcontextprotocol/sdk` | ^1.29 | MCP Protocol Implementation |
| `hono` | ^4.12 | HTTP Framework |
| `zod` | ^4.4 | Parameter Validation + Type Inference |
| `typescript` | ^5.9 | Type System |
| `vitest` | ^4.1 | Testing Framework |
**Only 3 production dependencies**, using the same tech stack as [Lyna](https://github.com/terrysun1216/lyna) project.
---
## Development
```bash
# Install dependencies
npm install
# Development run (stdio mode)
npm run dev
# Development run (HTTP mode)
npm run dev:http
# Run tests
npm test
# Build
npm run build
```
### Project Structure
```
src/
├── main.ts # CLI Entry
├── config.ts # Global Configuration
├── calendar.ts # Trading Calendar
├── server/ # MCP Server (stdio + HTTP)
├── tools/ # 12 MCP Tool Definitions
├── services/ # Business Logic Layer
├── providers/ # HTTP API Layer (Oriental Fortune/Sina/Xueqiu/F10)
├── indicators/ # 34 Technical Indicator Pure Functions
└── types/ # Zod Schema + TS Types
```
### Testing
All 13 E2E tests pass, verified with real data:
```bash
npm test # Unit tests
npx tsx tests/e2e-all-tools.test.ts # End-to-end tests
```
---
## License
MIT © Terry
---
## Acknowledgements
- [AKShare](https://github.com/akfamily/akshare) — Underlying data source research and reference
- [akshare-one-mcp](https://github.com/zwldarren/akshare-one-mcp) — Python version MCP reference implementation
- [Lyna](https://github.com/terrysun1216/lyna) — TypeScript MCP architecture reference
