everdeep/yfinance-mcp

Yahoo Finance MCP Server

A comprehensive Model Context Protocol (MCP) server that provides access to Yahoo Finance data including stock prices, financial statements, market analysis, options data, and more.

Features

This MCP server provides 30 tools organized into 7 categories:

Installation

Prerequisites

• Python 3.10 or higher
• uv package manager

Install with uv

# Clone the repository
git clone <repository-url>
cd yahoo-finance-mcp

# Install dependencies
uv sync

Usage

With Claude Desktop

Add this configuration to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "yahoo-finance": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/yahoo-finance-mcp",
        "run",
        "yahoo-finance-mcp"
      ]
    }
  }
}

With Claude Code

claude mcp add yahoo-finance --scope local -- uv --directory /path/to/yahoo-finance-mcp run yahoo-finance-mcp

Development Mode

Test the server using the MCP inspector:

# Run in development mode
uv run mcp dev src/yahoo_finance_mcp/server.py

This opens a web interface where you can test all the tools interactively.

As a Standalone Server

# Run the server
uv run yahoo-finance-mcp

Tool Examples

Get Stock Information

# Get comprehensive stock info
get_stock_info(ticker="AAPL")

# Get current price
get_current_price(ticker="MSFT")

# Get valuation metrics
get_market_cap(ticker="GOOGL")

Historical Data

# Get 1 year of daily data
get_historical_data(ticker="TSLA", period="1y", interval="1d")

# Get 5 days of hourly data
get_historical_data(ticker="NVDA", period="5d", interval="1h")

# Get dividend history
get_dividends(ticker="JNJ")

Financial Statements

# Get quarterly income statement
get_income_statement(ticker="AAPL", frequency="quarterly")

# Get annual balance sheet
get_balance_sheet(ticker="MSFT", frequency="annual")

# Get all financials at once
get_financials(ticker="GOOGL", frequency="quarterly")

Market Analysis

# Get analyst recommendations
get_analyst_recommendations(ticker="TSLA")

# Get price targets
get_analyst_price_targets(ticker="NVDA")

# Get earnings data
get_earnings(ticker="AAPL")

Options Data

# Get available expiration dates
get_options_dates(ticker="AAPL")

# Get full options chain for nearest expiration
get_options_chain(ticker="AAPL")

# Get options for specific date
get_options_chain(ticker="AAPL", expiration_date="2024-12-20")

# Get only calls
get_calls(ticker="AAPL", expiration_date="2024-12-20")

News & Insights

# Get latest 10 news articles
get_news(ticker="TSLA", limit=10)

# Get analyst upgrades/downgrades
get_upgrades_downgrades(ticker="NVDA")

Bulk Operations

# Compare multiple stocks
compare_stocks(tickers=["AAPL", "MSFT", "GOOGL"])

# Download historical data for multiple stocks
download_multiple(
    tickers=["AAPL", "MSFT", "GOOGL"],
    period="1mo",
    interval="1d"
)

Project Structure

yahoo-finance-mcp/
├── src/
│   └── yahoo_finance_mcp/
│       ├── __init__.py           # Package initialization
│       ├── server.py             # Main MCP server with tool registration
│       ├── models.py             # Pydantic models for validation
│       ├── utils.py              # Helper functions and utilities
│       └── tools/
│           ├── __init__.py
│           ├── stock_info.py    # Stock information tools
│           ├── historical.py    # Historical data tools
│           ├── financials.py    # Financial statement tools
│           ├── analysis.py      # Market analysis tools
│           ├── options.py       # Options data tools
│           ├── news.py          # News and insights tools
│           └── bulk.py          # Bulk operations tools
├── tests/
│   └── test_tools.py
├── pyproject.toml
├── README.md
└── .gitignore

Technical Details

Data Source

This server uses the yfinance library to fetch data from Yahoo Finance. Please note:

• This is an unofficial API and is intended for research and educational purposes
• Data availability and accuracy depend on Yahoo Finance
• Some data may not be available for all tickers
• Rate limiting may apply for excessive requests

Error Handling

All tools include comprehensive error handling and will return structured error responses when:

• Invalid ticker symbols are provided
• Data is not available for the requested ticker
• Network issues occur
• Invalid parameters are passed

Error responses follow this format:

{
  "error": true,
  "message": "Description of the error",
  "ticker": "SYMBOL"
}

Data Formatting

• All dates are returned in ISO 8601 format (YYYY-MM-DD or full datetime)
• Pandas DataFrames are converted to lists of dictionaries for easy consumption
• NaN/None values are handled gracefully
• Large datasets are formatted efficiently

Development

Running Tests

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=yahoo_finance_mcp

Adding New Tools

1. Create a new function in the appropriate tool module (or create a new module)
2. Import the function in server.py
3. Register it with the @mcp.tool() decorator
4. Add documentation to this README

Code Style

The project follows standard Python conventions:

• Type hints for all function parameters and returns
• Comprehensive docstrings
• Error handling for all external API calls
• Modular organization by functionality

Limitations

• Not for Production Trading: This server is for informational and research purposes only
• Data Accuracy: Relies on Yahoo Finance data accuracy and availability
• Rate Limiting: Heavy usage may encounter rate limits
• No Real-time Guarantees: Data may have delays depending on source
• Terms of Service: Users must comply with Yahoo Finance's Terms of Service

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Submit a pull request

Acknowledgments

• Built with FastMCP - The fast, Pythonic way to build MCP servers
• Data provided by yfinance
• Part of the Model Context Protocol ecosystem

Support

For issues, questions, or contributions, please open an issue on GitHub.

Disclaimer: This project is not affiliated with, endorsed by, or connected to Yahoo Finance or Yahoo Inc. Use at your own risk and ensure compliance with Yahoo Finance's Terms of Service.