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

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Enables AI assistants to access real-time financial data, historical stock prices, company information, financial statements, options data, market news, and analyst recommendations through Yahoo Finance. Built with FastMCP v2 for efficient HTTP streaming and comprehensive market analysis tools.

Related MCP Servers

MCP Stock Analysis Server
giptilabs
-
security
F
license
-
quality
Provides access to real-time and historical Indian stock data via Yahoo Finance API, enabling local LLMs to retrieve stock information through MCP-compatible agents like Claude Desktop and Cursor.
Last updated -
2
Yahoo Finance MCP Server
narumiruna
A
security
A
license
A
quality
A simple MCP server for Yahoo Finance using yfinance. This server provides a set of tools to fetch stock data, news, and other financial information.
Last updated -
5
51
MIT License
Finance MCP Server
botextractai
-
security
F
license
-
quality
A Model Context Protocol server built with FastMCP that provides financial data tools for AI agents, enabling them to access and analyze stock market information from Yahoo Finance through natural language queries.
Last updated -
2
Finance MCP Server
dino65-dev
-
security
A
license
-
quality
Provides real-time financial data from Yahoo Finance to Large Language Models through the Model Context Protocol, enabling AI models to access stock prices, historical data, and company information.
Last updated -
MIT License

View all related MCP servers