# Asia Market Data MCP Server

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

Works out of the box with **free, key-less data sources** — no accounts, no API keys. Install, connect your MCP client, and query.

## Features

- **Real-time stock quotes** — A-share, HK, and US markets
- **K-line / candlestick data** — historical OHLCV with multiple 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 (up to 20)

## Quick Start

### Run with `uvx` (no clone needed)

```bash
uvx --from git+https://github.com/timoranjes/asia-market-mcp asia-market-mcp
```

### Run from a clone

```bash
git clone https://github.com/timoranjes/asia-market-mcp
cd asia-market-mcp
pip install .
asia-market-mcp                      # stdio transport (default)
asia-market-mcp --http --port 9100   # streamable-HTTP transport
```

### Connect your MCP client

**Claude Desktop / Claude Code / any stdio client:**

```json
{
  "mcpServers": {
    "asia-market-data": {
      "command": "asia-market-mcp"
    }
  }
}
```

**HTTP client:**

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

## Data Sources & Fallbacks

The server picks the best available source per market and falls back automatically:

| Market | Primary | Fallback |
|--------|---------|----------|
| A-share (SH/SZ) | Tencent Finance API (free, real-time) | yfinance |
| Hong Kong | Tencent Finance API (free, real-time) | yfinance |
| US | yfinance | — |

**Optional enhancement:** if you have the Longbridge CLI installed and configured, it is detected automatically and preferred for US quotes (secondary for HK). Everything works without it — no setup, no keys, no account.

## 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 |

## Tools

| Tool | Description |
|------|-------------|
| `stock_quote` | Real-time quote for a single stock |
| `stock_quote_batch` | Batch quotes (up to 20 symbols; extra symbols are reported, not silently dropped) |
| `kline` | Historical OHLCV candlestick data (`period`: 1mo/3mo/6mo/1y) |
| `market_status` | Global market open/close status |
| `market_summary` | Major global indices summary |

## Example Usage

```
> Get the current price of Tencent
→ stock_quote(symbol="0700.HK")

> Show me the last 3 months of K-line data for Moutai
→ kline(symbol="600519.SH", period="3mo")

> What markets are open right now?
→ market_status()
```

## Development

```bash
git clone https://github.com/timoranjes/asia-market-mcp
cd asia-market-mcp
pip install -e ".[dev]"
pytest                 # offline unit tests (no network, no Longbridge needed)
python test_matrix.py  # live checks against a running server (optional)
```

CI runs the offline test suite on Python 3.10 and 3.12 for every push and PR.

## License

MIT — fork it, extend it, ship it.