Stock Data MCP Server

Production-ready aggregated MCP server for stock market data combining Finnhub (fundamentals), Yahoo Finance (quotes/history), Tushare (China A-shares), and Futu OpenAPI (HK/US/CN Real-time).

Perfect for building value investing agents, financial analysis tools, and portfolio management systems.

🎯 Features

🔍 9 Powerful Tools

1. search_symbol - Search stocks across all markets
2. resolve_symbol - normalize symbols between Yahoo (0700.HK) and Futu (HK.00700) formats
3. get_quote - Real-time quotes (Futu Snapshot / Yahoo Delay)
4. get_history - Historical OHLCV data (Futu K-line / Yahoo History)
5. get_fundamentals - ROE, margins, ratios, valuations
6. get_financial_statements - Income/Balance/Cashflow statements
7. subscribe_quote - Subscribe to real-time pushes (Futu)
8. get_order_book - Real-time market depth (Futu)
9. get_ticker - Real-time trade ticks (Futu)

Intelligent Data Routing

Market	Primary	Fallback
🇭🇰 港股	Futu OpenAPI	Yahoo Finance
🇨🇳 A股	Tushare Pro	Yahoo Finance
🇺🇸 美股	Yahoo Finance	-

• Fundamentals/Financials:
  • China (A-shares): Tushare Pro.
  • Global: Finnhub.
• Smart Caching: 5s for quotes, 1h for fundamentals, 24h for statements.

Multi-Market Support

Market	Symbol Format (Yahoo)	Futu Format	Examples
🇺🇸 US Stocks	SYMBOL	US.SYMBOL	AAPL, MSFT
🇭🇰 Hong Kong	CODE.HK	HK.CODE	0700.HK (HK.00700)
🇨🇳 Shanghai	CODE.SS	SH.CODE	600519.SS (SH.600519)
🇨🇳 Shenzhen	CODE.SZ	SZ.CODE	000001.SZ (SZ.000001)

📦 Installation

Prerequisites

1. Python 3.10+
2. Finnhub API Key (Free tier ok) - Register
3. Tushare Token (Optional, for A-share fundamentals) - Register
4. FutuOpenD (Optional, for Real-time HK/US/CN data)
   • Download and install FutuOpenD.
   • Login with your Futu account.
   • Keep it running (default port 11111).

Quick Start

# Clone or navigate to the project
cd stock-data-mcp

# Install with valid tools (uv recommended)
uv sync

# Set up environment
cp .env.example .env
# Edit .env and add your API keys

Environment Variables

Create a .env file:

# Data Provider Keys
FINNHUB_API_KEY=your_key_here
TUSHARE_TOKEN=your_token_here

# Futu Configuration (Optional)
FUTU_OPEND_HOST=127.0.0.1
FUTU_OPEND_PORT=11111

# Cache Settings
STOCK_MCP_TIMEOUT_SECONDS=10
STOCK_MCP_CACHE_TTL_QUOTE=5
STOCK_MCP_CACHE_TTL_FUNDAMENTALS=3600
STOCK_MCP_CACHE_TTL_STATEMENTS=86400

🚀 Usage

Running the Server

# Start the MCP server (stdio mode)
python -m stock_data_mcp

Claude Desktop Integration

macOS Configuration: Edit: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "stock-data": {
      "command": "/absolute/path/to/venv/bin/python",
      "args": ["-m", "stock_data_mcp"],
      "cwd": "/absolute/path/to/stock-data-mcp",
      "env": {
        "FINNHUB_API_KEY": "...",
        "TUSHARE_TOKEN": "...",
        "FUTU_OPEND_HOST": "127.0.0.1",
        "FUTU_OPEND_PORT": "11111"
      }
    }
  }
}

📚 API Reference Examples

Real-time Quotes (Futu/Yahoo)

// get_quote
{
  "symbol": "0700.HK",
  "prefer": "auto" // tries Futu -> Yahoo
}

Order Book (Futu Only)

// get_order_book
{
  "symbol": "0700.HK",
  "num": 10
}

Historical Data

// get_history
{
  "symbol": "600519.SS",
  "start_date": "2024-01-01",
  "end_date": "2024-01-31",
  "interval": "1d",
  "adjust": "qfq" // Forward adjusted
}

🔧 Error Handling

Errors return structured JSON with specific codes:

• PROVIDER_CONNECT_FAILED: FutuOpenD not reachable.
• HISTORY_NOT_AVAILABLE: Permission denied or no data.
• SUBSCRIPTION_LIMIT: Futu subscription quota exceeded.

🤝 Contributing

To add a new provider:

1. Create providers/new_provider.py
2. Implement provider interface
3. Add routing logic in server.py
4. Update tests and README

📄 License

MIT

Production-ready aggregated MCP server for stock market data combining Finnhub (fundamentals) and Yahoo Finance (quotes/history).

Perfect for building value investing agents, financial analysis tools, and portfolio management systems.

🎯 Features

5 Powerful Tools

1. search_symbol - Search stocks across all markets
2. get_quote - Real-time quotes with 5s caching
3. get_history - Historical OHLCV data
4. get_fundamentals - ROE, margins, ratios, valuations
5. get_financial_statements - Income/Balance/Cashflow statements

Intelligent Data Routing

• Quotes/History: Yahoo Finance (free, fast, no limits)
• Fundamentals/Financials: Finnhub (professional-grade data)
• Automatic Fallback: If primary source fails, tries backup
• Smart Caching: 5s for quotes, 1h for fundamentals, 24h for statements

Multi-Market Support

Market	Symbol Format	Examples
🇺🇸 US Stocks	SYMBOL	AAPL, MSFT, GOOGL
🇭🇰 Hong Kong	CODE.HK	0700.HK (Tencent), 9988.HK (Alibaba)
🇨🇳 Shanghai	CODE.SS	600519.SS (Moutai), 600036.SS (CMB)
🇨🇳 Shenzhen	CODE.SZ	000001.SZ (Pingan), 300750.SZ (CATL)

📦 Installation

Prerequisites

1. Python 3.10+
2. Finnhub API Key (free tier is fine)
   • Get yours at: https://finnhub.io/register
   • Free tier: 60 API calls/minute

Quick Start

# Clone or navigate to the project
cd stock-data-mcp

# Install with pip
pip install -e .

# Or with uv (faster)
uv pip install -e .

# Set up environment
cp .env.example .env
# Edit .env and add your FINNHUB_API_KEY

Environment Variables

Create a .env file:

# Required
FINNHUB_API_KEY=your_actual_api_key_here

# Optional (with defaults)
STOCK_MCP_TIMEOUT_SECONDS=10
STOCK_MCP_CACHE_TTL_QUOTE=5
STOCK_MCP_CACHE_TTL_FUNDAMENTALS=3600
STOCK_MCP_CACHE_TTL_STATEMENTS=86400

🚀 Usage

Running the Server

# Start the MCP server (stdio mode)
python -m stock_data_mcp

Testing Locally

# Run comprehensive tests
python quick_test.py

# Expected output:
# ✓ PASS: Yahoo Quote
# ✓ PASS: Yahoo History
# ✓ PASS: Finnhub Fundamentals
# ✓ PASS: Finnhub Statements

Claude Desktop Integration

macOS Configuration:

Edit: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "stock-data": {
      "command": "/absolute/path/to/venv/bin/python",
      "args": ["-m", "stock_data_mcp"],
      "cwd": "/absolute/path/to/stock-data-mcp",
      "env": {
        "FINNHUB_API_KEY": "your_api_key_here"
      }
    }
  }
}

Windows Configuration:

Edit: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "stock-data": {
      "command": "C:\\path\\to\\venv\\Scripts\\python.exe",
      "args": ["-m", "stock_data_mcp"],
      "cwd": "C:\\path\\to\\stock-data-mcp",
      "env": {
        "FINNHUB_API_KEY": "your_api_key_here"
      }
    }
  }
}

After configuration:

1. Completely quit Claude Desktop
2. Restart Claude Desktop
3. The tools will appear in your conversations

📚 API Reference

1. search_symbol

Search for stock symbols across markets.

Input:

{
  "query": "tencent",
  "limit": 10,
  "market_hint": "HK"
}

Output:

{
  "results": [
    {
      "symbol": "0700.HK",
      "name": "Tencent Holdings Ltd",
      "market": "HK",
      "exchange": "HKG",
      "source": "finnhub"
    }
  ]
}

Data Source: Finnhub → Yahoo (fallback)

---

2. get_quote

Get real-time market data.

Input:

{
  "symbol": "0700.HK",
  "prefer": "yahoo"
}

Output:

{
  "symbol": "0700.HK",
  "name": "Tencent Holdings Ltd",
  "market": "HK",
  "exchange": "HKG",
  "currency": "HKD",
  "price": 385.60,
  "change": 4.20,
  "change_pct": 1.10,
  "open": 382.00,
  "high": 387.20,
  "low": 380.50,
  "prev_close": 381.40,
  "volume": 15234000,
  "timestamp": "2025-12-12T14:30:00Z",
  "source": "yahoo"
}

Data Source: Yahoo (default) → Finnhub (fallback) Cache: 5 seconds

---

3. get_history

Get historical OHLCV data.

Input:

{
  "symbol": "600519.SS",
  "start_date": "2024-01-01",
  "end_date": "2024-12-31",
  "interval": "1d"
}

Intervals: 1d (daily), 1wk (weekly), 1mo (monthly)

Output:

{
  "symbol": "600519.SS",
  "records": [
    {
      "date": "2024-01-02",
      "open": 1650.00,
      "high": 1680.50,
      "low": 1645.00,
      "close": 1672.30,
      "volume": 8234500
    }
  ]
}

Data Source: Yahoo Finance Cache: 5 minutes

---

4. get_fundamentals

Get fundamental metrics (ROE, margins, ratios).

Input:

{
  "symbol": "AAPL",
  "period": "ttm"
}

Output:

{
  "symbol": "AAPL",
  "currency": "USD",
  "market_cap": 2890000000000,
  "pe": 29.45,
  "pb": 45.32,
  "ps": 7.58,
  "dividend_yield": 0.52,
  "roe": 147.25,
  "roa": 22.58,
  "gross_margin": 44.13,
  "operating_margin": 30.74,
  "net_margin": 25.31,
  "debt_to_equity": 1.96,
  "current_ratio": 0.98,
  "quick_ratio": 0.82,
  "revenue_ttm": 385603000000,
  "net_income_ttm": 97606000000,
  "free_cash_flow_ttm": 99584000000,
  "updated_at": "2025-12-12T14:30:00Z",
  "source": "finnhub"
}

Data Source: Finnhub (requires API key) Cache: 1 hour

---

5. get_financial_statements

Get income statement, balance sheet, or cashflow.

Input:

{
  "symbol": "AAPL",
  "statement": "income",
  "period": "annual"
}

Statement Types: income, balance, cashflow Periods: annual, quarterly

Output:

{
  "symbol": "AAPL",
  "statement": "income",
  "period": "annual",
  "currency": "USD",
  "items": [
    {
      "period_end": "2023-09-30",
      "revenue": 383285000000,
      "gross_profit": 169148000000,
      "operating_income": 114301000000,
      "net_income": 96995000000,
      "eps": 6.16
    }
  ],
  "source": "finnhub"
}

Data Source: Finnhub (requires API key) Cache: 24 hours

🏗️ Architecture

stock-data-mcp/
├── stock_data_mcp/
│   ├── server.py              # MCP server + routing logic
│   ├── schemas.py             # Unified Pydantic models
│   ├── cache.py               # TTL caching system
│   ├── util.py                # Helper functions
│   └── providers/
│       ├── finnhub_provider.py    # Finnhub integration
│       ├── yahoo_provider.py      # Yahoo Finance integration
│       └── symbols.py             # Symbol normalization
├── pyproject.toml
├── .env.example
└── quick_test.py

Data Flow

User Request
    ↓
MCP Server (routing + caching)
    ↓
┌─────────────┬─────────────┐
│   Yahoo     │  Finnhub    │
│  Provider   │  Provider   │
└─────────────┴─────────────┘
    ↓              ↓
Unified Schema Response

🔧 Error Handling

All errors return structured JSON:

{
  "error": {
    "code": "PROVIDER_RATE_LIMIT",
    "message": "Finnhub API rate limit exceeded",
    "details": {
      "provider": "finnhub",
      "symbol": "AAPL"
    }
  }
}

Error Codes:

• PROVIDER_TIMEOUT - Request timed out
• SYMBOL_NOT_FOUND - Invalid or unknown symbol
• INVALID_ARGUMENT - Bad input parameters
• PROVIDER_RATE_LIMIT - API rate limit hit
• PROVIDER_ERROR - Provider-specific error
• MISSING_API_KEY - Finnhub key not configured
• NO_DATA - No data available for request

💡 Usage Examples with Claude

Once integrated, you can ask Claude:

"Compare the fundamentals of Tencent (0700.HK) and Alibaba (9988.HK).
Show me ROE, profit margins, and debt ratios."

"Get the last 5 years of annual financial statements for AAPL.
Calculate revenue growth rate and profit margin trends."

"Find Chinese tech stocks with ROE > 15% and PE < 20.
Show me their recent price performance."

🎯 Use Cases

Value Investing Analysis

• Screen stocks by ROE, margins, debt ratios
• Compare fundamentals across markets
• Track historical performance metrics

Portfolio Management

• Monitor real-time quotes for watchlist
• Analyze sector allocations
• Track dividend yields

Financial Research

• Pull complete financial statements
• Calculate custom metrics
• Build valuation models

⚙️ Configuration

Cache TTL Settings

Adjust in .env:

STOCK_MCP_CACHE_TTL_QUOTE=5          # Quote cache (seconds)
STOCK_MCP_CACHE_TTL_FUNDAMENTALS=3600 # Fundamentals (1 hour)
STOCK_MCP_CACHE_TTL_STATEMENTS=86400  # Statements (24 hours)

Rate Limits

Finnhub Free Tier:

• 60 API calls/minute
• 30 calls/second

Best Practices:

• Enable caching (default)
• Batch similar requests
• Use Yahoo for high-frequency quote checks

🐛 Troubleshooting

"MISSING_API_KEY" error

# Check if env var is set
echo $FINNHUB_API_KEY

# If using .env file, verify it's loaded
cat .env | grep FINNHUB

# Restart server after setting

Server not appearing in Claude Desktop

1. Check JSON syntax in config file
2. Use absolute paths (not ~ or relative paths)
3. Verify Python path with which python in your venv
4. Check logs:

   # macOS
   tail -f ~/Library/Logs/Claude/mcp*.log
   
   # Windows
   Get-Content $env:APPDATA\Claude\logs\mcp*.log -Wait
   

Symbol not found

• Verify symbol format (e.g., 0700.HK not 700.HK)
• Try searching first: search_symbol("tencent")
• Check if market is supported

Rate limit exceeded

• Increase cache TTL
• Reduce request frequency
• Consider Finnhub paid tier for higher limits

📊 Performance

Typical Response Times:

• Quote (cached): <10ms
• Quote (fresh): 200-500ms
• History (1 year): 500-1000ms
• Fundamentals (cached): <10ms
• Fundamentals (fresh): 1-2s
• Statements: 1-3s

Cache Hit Rates:

• Quotes: ~80% (5s TTL)
• Fundamentals: ~95% (1h TTL)
• Statements: ~99% (24h TTL)

🚀 Roadmap

v0.2 (Planned)

• [ ] Symbol mapping table (watchlist.csv)
• [ ] Company profile tool
• [ ] News & sentiment data
• [ ] Insider trading data

v0.3 (Future)

• [ ] Alternative data sources (Alpha Vantage, IEX)
• [ ] Crypto support
• [ ] Options data
• [ ] Technical indicators

🤝 Contributing

This is a production-ready MVP. Extensions welcome!

To add a new provider:

1. Create providers/new_provider.py
2. Implement provider interface
3. Add routing logic in server.py
4. Update tests and README

📄 License

MIT

🙏 Acknowledgments

• Finnhub - Professional-grade financial data API
• Yahoo Finance (yfinance) - Free historical data
• MCP - Model Context Protocol by Anthropic

---

Built for value investors who code. 🚀📈