Stock Data

You get a production-ready MCP server that aggregates stock market data from Finnhub, Yahoo Finance, Tushare, and Futu OpenAPI. It provides real-time quotes, history, fundamentals, financial statements, and optional real-time feeds, enabling you to build value investing tools, financial analyses, and portfolio trackers with consistent, cached responses.

How to use

You run the MCP server locally and connect your MCP client to request data such as real-time quotes, historical OHLCV data, and company fundamentals. The server handles data routing, caching, and normalization across markets, so you can build cross-market analytics and investment tooling without managing multiple data sources.

How to install

Prerequisites you need before you start:

• Python 3.10+
• Finnhub API Key (free tier is okay)
• Tushare Token (optional for A-share fundamentals)
• FutuOpenD (optional for real-time HK/US/CN data)

Follow these steps to install and run the server locally.

# 1) Navigate to the project directory
cd stock-data-mcp

# 2) Start installation in editable mode (stdlib-based runtime)
# If you have uv installed for speed, you can use it instead of plain Python
uv sync

# 3) Create and populate environment variables
cp .env.example .env
# Edit .env and add your API keys as needed

Configuration and startup

Set up environment variables to authorize data providers and to configure optional components. The server reads these at startup to access Finnhub, Tushare, and Futu OpenD if you enable it.

# Example environment variables
FINNHUB_API_KEY=your_key_here
TUSHARE_TOKEN=your_token_here

# Optional Futu OpenD configuration (if you run real-time feeds)
FUTU_OPEND_HOST=127.0.0.1
FUTU_OPEND_PORT=11111

# Cache and timeout settings (adjust to your needs)
STOCK_MCP_TIMEOUT_SECONDS=10
STOCK_MCP_CACHE_TTL_QUOTE=5
STOCK_MCP_CACHE_TTL_FUNDAMENTALS=3600
STOCK_MCP_CACHE_TTL_STATEMENTS=86400

Running the server

Start the MCP server in stdio mode so you can connect to it from your MCP client using a local command line.

python -m stock_data_mcp

Claude Desktop integration (optional)

If you use Claude Desktop, add a local MCP server configuration that points to the Python module you started above. Provide the key environment values to access Finnhub and, if applicable, Futu OpenD.

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

Available tools

search_symbol

Search stocks across markets to find matching symbols and names.

resolve_symbol

Normalize symbols between different market formats (Yahoo, Futu) for consistent queries.

get_quote

Fetch real-time quotes with caching for fast responses.

get_history

Retrieve historical OHLCV data from Yahoo Finance or Futu.

get_fundamentals

Obtain fundamental metrics such as ROE, margins, and valuations.

get_financial_statements

Get income statement, balance sheet, and cash flow data.

subscribe_quote

Subscribe to real-time quote pushes from supported providers.

get_order_book

Fetch real-time market depth data.

get_ticker

Receive real-time trade ticks.