StockMCP delivers a real-time stock market data MCP server built around the Model Context Protocol. It exposes a JSON-RPC 2.0–compliant interface you can query from AI apps, trading bots, or financial tools to access quotes, fundamentals, history, and forecasts sourced from Yahoo Finance.

How to use

You connect to StockMCP from any MCP client by pointing it at the HTTP MCP endpoint and using the available tools to fetch data. The primary endpoint is hosted at a remote URL, so you can start querying immediately after you configure your client.

How to install

Prerequisites you need before you begin are a running Python environment and Docker if you plan to containerize the server.

Option 1 — Docker (recommended for quick setup)

# Build the image
Dockerfile
# Run the container

Build and run from the provided Dockerfile

# Build the image
docker build -t stockmcp .

# Run the container
docker run -p 3001:3001 stockmcp

# Run in background
docker run -d -p 3001:3001 --name stockmcp stockmcp

Option 2 — Local development (Python environment)

# Install dependencies
uv sync

# Or with pip
pip install -e .

# Configure your API key (see API Key Setup above)
cp .env.example .env
# Edit .env with your Alpha Vantage API key

# Run the server
python src/main.py
# Server runs on http://localhost:3001/mcp

Additional setup notes

If you choose to run locally, you can expose the server on a different port by adjusting the Docker run command or the Python startup configuration accordingly.

MCP client integration example for immediate access

You can use the free hosted endpoint to start querying data right away. The endpoint is designed for quick MCP client setup without needing a key.

Notes on environment and data sources

Primary data comes from Yahoo Finance via yfinance, enabling real-time quotes and historical data. A supplementary Alpha Vantage key can be added for extended earnings estimates and forecasts if you choose to provide it.

Available tools

get_realtime_quote

Retrieve current market data including price, volume, market cap, and key financial ratios

get_fundamentals

Access comprehensive financial statements (income, balance sheet, cash flow) and calculated ratios

get_price_history

Get historical OHLCV data with optional total return calculation including reinvested dividends

get_dividends_and_actions

Analyze dividend payment history and corporate actions with quality metrics and consistency scoring

get_analyst_forecasts

Get analyst price targets, consensus ratings (Buy/Hold/Sell), and EPS forecasts from professional analysts

get_growth_projections

Forward growth projections for revenue, earnings (EPS), and free cash flow with 1-year, 3-year, and 5-year CAGR estimates