Skip to main content
Glama
wallacetju

Stock Data MCP Server

by wallacetju
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

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)

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. πŸš€πŸ“ˆ

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

Resources

Appeared in Searches

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/wallacetju/myStockMCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server