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

1. Fork the repository
2. Create a feature branch
3. Add new tools or improve existing ones
4. Update tests and documentation
5. Submit a pull request

License

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

Troubleshooting

Common Issues

1. Server won't start: Check if port 8000 is available
2. Tool failures: Verify internet connection for Yahoo Finance API
3. 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