Yahoo Finance MCP Server

A Model Context Protocol (MCP) server that provides Yahoo Finance data through FastMCP v2 with HTTP streaming support. This server enables AI assistants to access real-time financial data, historical prices, company information, and market analysis tools. The server is primarily built for ThinkingSand AI agents, but can be deployed locally as well.

Features

Real-time Stock Data: Current prices, historical data, and company information
Financial Statements: Income statements, balance sheets, and cash flow data
Options Trading: Option chains, expiration dates, and pricing data
Market News: Latest financial news and analysis
Institutional Data: Holder information and insider transactions
Analyst Coverage: Recommendations and upgrades/downgrades
HTTP Streaming: Fast, efficient data delivery with FastMCP v2

Available Tools

Tool	Description	Parameters
`get_historical_stock_prices`	Historical stock price data	`ticker`, `period`, `interval`
`get_stock_info`	Comprehensive company and stock information	`ticker`
`get_yahoo_finance_news`	Latest news articles for a stock	`ticker`
`get_stock_actions`	Dividend and stock split history	`ticker`
`get_financial_statement`	Financial statements (income, balance, cashflow)	`ticker`, `financial_type`
`get_holder_info`	Institutional and insider holder data	`ticker`, `holder_type`
`get_option_expiration_dates`	Available options expiration dates	`ticker`
`get_option_chain`	Option chain data for calls and puts	`ticker`, `expiration_date`, `option_type`
`get_recommendations`	Analyst recommendations and upgrades	`ticker`, `recommendation_type`, `months_back`

Installation & Setup

Prerequisites

Python 3.11 or higher
uv package manager

Using uv (Recommended)

# Clone the repository
git clone https://github.com/citizenhicks/yahoo-finance-mcp.git
cd yahoo-finance-mcp

# Install dependencies
uv sync

# Run the server
uv run python server.py

Configuration

Environment Variables

Create a .env file (copy from .env.example):

# Server configuration
HOST=127.0.0.1      # Server host
PORT=8000           # Server port
LOG_LEVEL=INFO      # Logging level

Starting the Server

uv run python server.py

The server will start on http://127.0.0.1:8000 by default and display:

Starting Yahoo Finance MCP Server locally on 127.0.0.1:8000...

Tool Documentation

1. Historical Stock Prices

get_historical_stock_prices(ticker="AAPL", period="1mo", interval="1d")

ticker: Stock symbol (e.g., "AAPL", "TSLA", "GOOGL")
period: 1d, 5d, 1mo, 3mo, 6mo, 1y, 2y, 5y, 10y, ytd, max
interval: 1m, 2m, 5m, 15m, 30m, 60m, 90m, 1h, 1d, 5d, 1wk, 1mo, 3mo

2. Stock Information

get_stock_info(ticker="AAPL")

Returns comprehensive company data including current price, market cap, financial metrics, and company details.

3. Financial Statements

get_financial_statement(ticker="AAPL", financial_type="income_stmt")

financial_type: income_stmt, quarterly_income_stmt, balance_sheet, quarterly_balance_sheet, cashflow, quarterly_cashflow

4. Holder Information

get_holder_info(ticker="AAPL", holder_type="institutional_holders")

holder_type: major_holders, institutional_holders, mutualfund_holders, insider_transactions, insider_purchases, insider_roster_holders

5. Options Data

# Get available expiration dates
get_option_expiration_dates(ticker="AAPL")

# Get option chain
get_option_chain(ticker="AAPL", expiration_date="2024-01-19", option_type="calls")

option_type: calls or puts

6. Recommendations

get_recommendations(ticker="AAPL", recommendation_type="recommendations", months_back=12)

recommendation_type: recommendations, upgrades_downgrades
months_back: Number of months for historical upgrades/downgrades

MCP Client Integration

Claude Desktop

Add to your Claude Desktop MCP settings (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "yahoo-finance": {
      "command": "uv",
      "args": ["run", "python", "/path/to/yahoo-finance-mcp/server.py"],
      "env": {
        "HOST": "127.0.0.1",
        "PORT": "8000"
      }
    }
  }
}

HTTP Client Integration

Connect directly to the HTTP endpoint:

http://127.0.0.1:8000

Python Client Example

import asyncio
from fastmcp import Client

async def example():
    client = Client("http://127.0.0.1:8000")

    async with client:
        # Get Apple stock info
        result = await client.call_tool("get_stock_info", {"ticker": "AAPL"})
        print(result)

        # Get historical prices
        result = await client.call_tool("get_historical_stock_prices", {
            "ticker": "AAPL",
            "period": "1y",
            "interval": "1d"
        })
        print(result)

asyncio.run(example())

Project Structure

yahoo-finance-mcp/
├── server.py              # Main FastMCP server implementation
├── main.py               # Alternative entry point
├── pyproject.toml        # Project dependencies and metadata
├── .env.example          # Environment configuration template
├── .env                  # Your local environment variables (gitignored)
└── README.md             # This documentation

Error Handling

The server includes robust error handling:

Invalid tickers: Returns clear error messages for non-existent symbols
Missing data: Graceful handling when specific data isn't available
Network issues: Proper error reporting for Yahoo Finance API issues
Parameter validation: Clear error messages for invalid parameters

Example error response:

"Error: Company ticker INVALID123 not found"

Data Sources

All financial data is sourced from Yahoo Finance through the yfinance Python library:

Stock prices: Real-time and historical market data
Company information: Fundamentals, metrics, and company details
Financial statements: Official SEC filings and quarterly reports
Options data: Real-time options chains and pricing
News: Latest financial news and analyst coverage
Institutional data: Holdings and insider transaction data

Production Deployment

Docker (Optional)

FROM python:3.11-slim

WORKDIR /app
COPY . .

RUN pip install uv
RUN uv sync

EXPOSE 8000

CMD ["uv", "run", "python", "server.py"]

Environment Variables for Production

HOST=0.0.0.0
PORT=8000
LOG_LEVEL=INFO

Contributing

Fork the repository
Create a feature branch
Add new tools or improve existing ones
Update tests and documentation
Submit a pull request

License

This project is open source. Yahoo Finance data is subject to Yahoo's terms of service.

Troubleshooting

Common Issues

Server won't start: Check if port 8000 is available
Tool failures: Verify internet connection for Yahoo Finance API
Import errors: Ensure all dependencies are installed with uv sync

Debug Mode

Set LOG_LEVEL=DEBUG in your .env file for detailed logging.

Support

FastMCP Issues: FastMCP Documentation
Server Issues: Open an issue in this repository

Built with FastMCP v2 and yfinance