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
| 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
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...
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
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
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:
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
Built with FastMCP v2 and yfinance