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

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

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

3. Run the server

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:

{
  "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

{
  "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

{
  "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