# A-Stock MCP Server 🇨🇳📈

A Model Context Protocol (MCP) server providing **Chinese A-Share stock market data** — real-time quotes, historical K-lines, market scanning, and intelligent stock screening.

**Zero API key required.** Powered by [BaoStock](https://baostock.com/) (free) + Sina Finance API.

## Features

### 🛠 MCP Tools

| Tool | Description | Example |
|------|-------------|---------|
| `get_quote` | Real-time quote for one or more stocks | "茅台实时报价" |
| `get_kline` | Historical K-line data (daily/weekly/monthly/5min/15min/30min/60min) | "宁德时代最近60日K线" |
| `get_stock_list` | List all A-share stocks with filtering | "列出所有沪深300成分股" |
| `scan_market` | Market scan: top gainers, losers, volume leaders, active stocks | "今日涨幅前20" |
| `screen_stocks` | Multi-factor stock screening (price, volume, MA, sector) | "放量突破MA20的股票" |
| `get_stock_info` | Company fundamentals: industry, listing date, description | "比亚迪公司信息" |
| `get_dividend` | Dividend history for a stock | "长江电力分红记录" |

### Key Highlights

- **6937+ A-share stocks** covered (SH + SZ)
- **Zero cost** — no API keys, no subscriptions
- **Real-time** quotes via Sina API
- **Historical data** up to 20+ years via BaoStock
- **Smart screening** — combine price, volume, MA, and sector filters
- **Batch queries** — ask for multiple stocks at once

## Installation

### Option 1: pip (recommended)

```bash
pip install astock-mcp-server
```

### Option 2: uvx (no install)

```bash
uvx astock-mcp-server
```

### Option 3: From source

```bash
git clone https://github.com/yunjie/astock-mcp-server.git
cd astock-mcp-server
pip install -e .
```

## Configuration

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "astock": {
      "command": "uvx",
      "args": ["astock-mcp-server"]
    }
  }
}
```

### Cursor / VS Code

Add to your MCP settings:

```json
{
  "mcpServers": {
    "astock": {
      "command": "python",
      "args": ["-m", "astock_mcp.server"]
    }
  }
}
```

### Hermes Agent

Add to your `config.yaml`:

```yaml
mcp:
  servers:
    astock:
      command: "uvx"
      args: ["astock-mcp-server"]
```

## Usage Examples

Once connected, your AI assistant can:

```
"帮我查一下贵州茅台和宁德时代的实时报价"
→ Uses get_quote with codes ["600519.SH", "300750.SZ"]

"找出今天涨幅超过5%且成交额超过10亿的股票"
→ Uses scan_market with filters

"比亚迪最近一年的周K线数据"
→ Uses get_kline with frequency="w" and periods=52

"筛选价格在20-50元之间、放量突破20日均线、属于新能源板块的股票"
→ Uses screen_stocks with multi-factor filters
```

## Data Sources

| Source | Data | Cost | Coverage |
|--------|------|------|----------|
| **BaoStock** | Historical K-lines, stock list, fundamentals, dividends | Free | 1990-present |
| **Sina Finance** | Real-time quotes, market rankings | Free | All A-shares |

## Stock Code Format

Use standard A-share codes with exchange suffix:

- Shanghai (上交所): `600519.SH`, `601318.SH`
- Shenzhen (深交所): `000858.SZ`, `300750.SZ`
- Beijing (北交所): `872925.BJ`

## Limitations

- Real-time quotes have ~3 second delay (not for HFT)
- BaoStock data updates after market close (no intraday historical yet)
- Rate limiting: BaoStock ~100 requests/min, Sina ~60 requests/min

## License

MIT — use freely, no warranty.

## Contributing

Issues and PRs welcome! This is an open-source project.