# Asia Market Data MCP Server

Real-time financial market data for **A-share (China)**, **Hong Kong**, and **US markets** via the Model Context Protocol.

The only MCP server covering Asia-Pacific market data — the gap that no existing financial data MCP fills.

## Features

- **Real-time stock quotes** — A-share, HK, and US markets
- **K-line / candlestick data** — Historical OHLCV with multiple time periods
- **Market status** — Live trading session status for US, HK, and CN
- **Market summary** — Major global indices (S&P 500, NASDAQ, Dow, Hang Seng, SSE, CSI 300)
- **Batch quotes** — Multiple stocks in a single call

## Symbol Format

`CODE.MARKET` — e.g. `600519.SH`, `0700.HK`, `NVDA.US`

| Market | Code | Exchange |
|--------|------|----------|
| SH | Shanghai Stock Exchange | A-shares |
| SZ | Shenzhen Stock Exchange | A-shares |
| HK | Hong Kong Stock Exchange | HK stocks |
| US | US markets | NYSE, NASDAQ |

## Data Sources

| Market | Primary Source | Fallback | Latency |
|--------|---------------|----------|---------|
| A-share (SH/SZ) | Tencent Finance API | yfinance | Real-time |
| Hong Kong | Tencent Finance API | Longbridge CLI | Real-time |
| US | Longbridge CLI | yfinance | Real-time |

All data sources are free-tier APIs. No API keys required for basic usage.

## Quick Start

### With Claude Desktop / Claude Code

Add to your MCP config:

```json
{
  "mcpServers": {
    "asia-market-data": {
      "url": "http://YOUR_SERVER:9100/mcp",
      "transport": "streamable-http"
    }
  }
}
```

### With any MCP client (stdio)

```bash
pip install fastmcp requests yfinance
python server.py
```

## Tools

| Tool | Description | Price |
|------|-------------|-------|
| `stock_quote` | Real-time quote for a single stock | Free |
| `stock_quote_batch` | Batch quotes for multiple stocks | Free |
| `kline` | Historical OHLCV candlestick data | Free |
| `market_status` | Global market open/close status | Free |
| `market_summary` | Major global indices summary | Free |

## Example Usage

```
> Get the current price of Tencent
→ stock_quote(symbol="0700.HK")
→ Returns: { "last_price": 419.0, "change_pct": -1.64, ... }

> Show me the last 3 months of K-line data for Moutai
→ kline(symbol="600519.SH", period="3mo")
→ Returns: { "count": 64, "klines": [...] }

> What markets are open right now?
→ market_status()
→ Returns: { "US": "closed", "HK": "closed", "CN": "closed" }
```

## Roadmap

- [x] Phase 1: Free data sources, no payment gate (current)
- [ ] Phase 2: x402 per-call billing for premium tools
- [ ] Phase 3: Licensed data sources (EODHD, Longbridge commercial API)
- [ ] Phase 4: WebSocket real-time streaming

## License

MIT