# finance-data-mcp

A **Model Context Protocol (MCP)** server that provides unified financial data access across multiple markets and data sources.

## Features

- 🇺🇸 **US / ETF**: Alpha Vantage (primary) → yfinance (fallback)
- 🇨🇳 **A-share**: Tushare (primary) → AKShare (fallback) → yfinance
- 🇭🇰 **HK stocks**: AKShare (primary) → yfinance (fallback)
- 💱 **FX rates**: exchangerate-api → AKShare → Alpha Vantage → yfinance
- 🔄 **Automatic fallback** across data sources on failure
- 🔑 **Multi-key rotation** for Alpha Vantage (extends daily quota)
- 🌐 **Proxy support** for AKShare (useful when running overseas)

## MCP Tools

| Tool | Description |
|------|-------------|
| `get_stock_price` | Real-time stock price with market routing |
| `get_financial_report` | Income statement, balance sheet, cash flow |
| `get_financial_summary` | PE, PB, ROE, market cap, EPS, etc. |
| `get_fx_rate` | Currency exchange rates |

## Quick Start

### 1. Install dependencies

```bash
pip install -r requirements.txt
```

> **Note**: Not all data sources are required. Install only what you need:
> - `akshare` — for A-share and HK stocks
> - `tushare` — for A-share (needs token, no IP restriction)
> - `yfinance` — for all markets (fallback, no key needed)
> - `requests` — required for Alpha Vantage

### 2. Configure environment

```bash
cp .env.example .env
# Edit .env with your API keys
```

### 3. Run the server

```bash
python finance_data_server.py
```

The server runs in **stdio mode** (standard MCP transport).

### 4. Configure in your MCP client

Example configuration for MCP clients:

```json
{
  "mcpServers": {
    "finance-data": {
      "command": "python",
      "args": ["/path/to/finance-data-mcp/finance_data_server.py"],
      "env": {}
    }
  }
}
```

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `ALPHAVANTAGE_API_KEYS` | For US stocks | Comma-separated Alpha Vantage API keys |
| `TUSHARE_TOKEN` | For A-share | Tushare Pro API token |
| `AKSHARE_PROXY` | Optional | HTTP proxy for AKShare (format: `http://user:pass@host:port`) |

## Architecture

```
finance_data_server.py          # MCP Server entry point + MarketRouter
├── datasources/
│   ├── alpha_vantage_adapter.py  # US/ETF stocks (Alpha Vantage API)
│   ├── akshare_adapter.py        # A-share / HK stocks (AKShare + East Money)
│   ├── tushare_adapter.py        # A-share stocks (Tushare Pro API)
│   └── yfinance_adapter.py       # All markets fallback (Yahoo Finance)
├── alpha_vantage_client.py       # Alpha Vantage HTTP client
└── alpha_vantage_rate_limiter.py # Per-key rate limiting with persistence
```

### Data Flow

```
MCP Client Request
       │
       ▼
  MarketRouter (routes by market type)
       │
       ├─ US/ETF ──→ AlphaVantage → yfinance
       ├─ A-share ──→ Tushare → AKShare → yfinance
       └─ HK ──────→ AKShare → yfinance
```

## Standardized Output

All adapters return data in a unified format:

### Price Response
```json
{
  "symbol": "AAPL",
  "market": "US",
  "price": 185.50,
  "change": 2.30,
  "change_pct": 1.25,
  "volume": 52340000,
  "high": 186.20,
  "low": 183.10,
  "open": 183.80,
  "previous_close": 183.20,
  "currency": "USD",
  "source": "alpha_vantage"
}
```

### Financial Report Response
```json
{
  "symbol": "AAPL",
  "market": "US",
  "report_type": "income_statement",
  "period": "annual",
  "data": [
    {
      "period": "2024-09-30",
      "revenue": 391035000000,
      "net_income": 93736000000,
      "eps_basic": 6.11
    }
  ],
  "count": 5,
  "source": "alpha_vantage"
}
```

## License

MIT