README.md•8.24 kB
# 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](https://docs.astral.sh/uv/) package manager
### Using uv (Recommended)
```bash
# 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`):
```bash
# Server configuration
HOST=127.0.0.1 # Server host
PORT=8000 # Server port
LOG_LEVEL=INFO # Logging level
```
### Starting the Server
```bash
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
```python
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
```python
get_stock_info(ticker="AAPL")
```
Returns comprehensive company data including current price, market cap, financial metrics, and company details.
### 3. Financial Statements
```python
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
```python
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
```python
# 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
```python
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`):
```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
```python
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)
```dockerfile
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
```bash
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](https://gofastmcp.com)
- **Server Issues**: Open an issue in this repository
---
Built with FastMCP v2 and yfinance