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

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