# 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