How do I use Yahoo Finance MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Yahoo Finance MCP Server get historical stock prices for AAPL over the last month" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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

Related MCP server: Yahoo Finance MCP Server

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

Yahoo Finance MCP Server

Yahoo Finance MCP Server

Features

Available Tools

Installation & Setup

Prerequisites

Using uv (Recommended)

Configuration

Environment Variables

Starting the Server

Tool Documentation

1. Historical Stock Prices

2. Stock Information

3. Financial Statements

4. Holder Information

5. Options Data

6. Recommendations

MCP Client Integration

Claude Desktop

HTTP Client Integration

Python Client Example

Project Structure

Error Handling

Data Sources

Production Deployment

Docker (Optional)

Environment Variables for Production

Contributing

License

Troubleshooting

Common Issues

Debug Mode

Support

Resources

Appeared in Searches

New MCP Servers

Latest Blog Posts

MCP directory API