yahoo-finance-mcp-server 0.1.2
A Model Context Protocol (MCP) server for Yahoo Finance data access
Requires Python: >=3.10
Keywords: ai, finance, mcp, stock-market, yahoo-finance

# Yahoo Finance MCP Server

A Model Context Protocol (MCP) server that provides access to Yahoo Finance data. This server enables AI assistants to fetch real-time stock prices, financial statements, news, options data, and more through a standardized interface.

## Features

- **Historical Stock Prices**: Get historical price data with customizable periods and intervals
- **Stock Information**: Access comprehensive stock data including financials, metrics, and company info
- **Financial Statements**: Retrieve income statements, balance sheets, and cash flow statements
- **News**: Fetch latest news articles for any ticker
- **Options Data**: Get option chains, expiration dates, and options analytics
- **Holder Information**: Access institutional, mutual fund, and insider holder data
- **Analyst Recommendations**: Get analyst ratings, upgrades, and downgrades
- **Corporate Actions**: Track dividends and stock splits

## Installation

### Using uvx (Recommended)

The easiest way to use this MCP server is with `uvx`, which runs it directly without installation:

```bash
uvx yahoo-finance-mcp-server
```

### Using uv

Install the package using `uv`:

```bash
uv pip install yahoo-finance-mcp-server
```

### Using pip

```bash
pip install yahoo-finance-mcp-server
```

### From Source

```bash
git clone https://github.com/laxmimerit/yahoo-finance-mcp-server.git
cd yahoo-finance-mcp-server
uv pip install -e .
```

## Configuration

### Claude Desktop Configuration

Add this to your Claude Desktop configuration file:

**MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

#### Using uvx (Recommended):

```json
{
  "mcpServers": {
    "yahoo-finance": {
      "command": "uvx",
      "args": ["yahoo-finance-mcp-server"]
    }
  }
}
```

#### Using uv:

```json
{
  "mcpServers": {
    "yahoo-finance": {
      "command": "uv",
      "args": ["run", "yahoo-finance-mcp-server"]
    }
  }
}
```

#### Using Python directly:

```json
{
  "mcpServers": {
    "yahoo-finance": {
      "command": "python",
      "args": ["-m", "yahoo_finance_mcp_server.server"]
    }
  }
}
```

### Other MCP Clients

For other MCP clients that support stdio transport, you can run:

```bash
yahoo-finance-mcp-server
```

Or with uvx:

```bash
uvx yahoo-finance-mcp-server
```

## Available Tools

### 1. get_historical_stock_prices

Get historical stock prices for a ticker symbol.

**Parameters:**
- `ticker` (str): Stock ticker symbol (e.g., "AAPL")
- `period` (str, optional): Valid periods: 1d, 5d, 1mo, 3mo, 6mo, 1y, 2y, 5y, 10y, ytd, max. Default: "1mo"
- `interval` (str, optional): Valid intervals: 1m, 2m, 5m, 15m, 30m, 60m, 90m, 1h, 1d, 5d, 1wk, 1mo, 3mo. Default: "1d"

**Example:**
```
Get historical prices for Apple stock over the last year
```

### 2. get_stock_info

Get comprehensive stock information including price, company details, financial metrics, and more.

**Parameters:**
- `ticker` (str): Stock ticker symbol (e.g., "TSLA")

**Example:**
```
Get detailed information about Tesla stock
```

### 3. get_yahoo_finance_news

Get latest news articles for a ticker symbol.

**Parameters:**
- `ticker` (str): Stock ticker symbol (e.g., "GOOGL")

**Example:**
```
Get recent news about Google
```

### 4. get_stock_actions

Get dividend and stock split history.

**Parameters:**
- `ticker` (str): Stock ticker symbol (e.g., "MSFT")

**Example:**
```
Get dividend history for Microsoft
```

### 5. get_financial_statement

Get financial statements (income statement, balance sheet, or cash flow).

**Parameters:**
- `ticker` (str): Stock ticker symbol (e.g., "AMZN")
- `financial_type` (str): One of: `income_stmt`, `quarterly_income_stmt`, `balance_sheet`, `quarterly_balance_sheet`, `cashflow`, `quarterly_cashflow`

**Example:**
```
Get Amazon's quarterly income statement
```

### 6. get_holder_info

Get holder and ownership information.

**Parameters:**
- `ticker` (str): Stock ticker symbol (e.g., "NVDA")
- `holder_type` (str): One of: `major_holders`, `institutional_holders`, `mutualfund_holders`, `insider_transactions`, `insider_purchases`, `insider_roster_holders`

**Example:**
```
Get institutional holders of NVIDIA
```

### 7. get_option_expiration_dates

Get available options expiration dates for a ticker.

**Parameters:**
- `ticker` (str): Stock ticker symbol (e.g., "SPY")

**Example:**
```
Get option expiration dates for SPY
```

### 8. get_option_chain

Get option chain data for calls or puts.

**Parameters:**
- `ticker` (str): Stock ticker symbol (e.g., "AAPL")
- `expiration_date` (str): Expiration date in YYYY-MM-DD format
- `option_type` (str): Either "calls" or "puts"

**Example:**
```
Get Apple call options expiring on 2024-12-20
```

### 9. get_recommendations

Get analyst recommendations and upgrades/downgrades.

**Parameters:**
- `ticker` (str): Stock ticker symbol (e.g., "META")
- `recommendation_type` (str): Either "recommendations" or "upgrades_downgrades"
- `months_back` (int, optional): Number of months to look back. Default: 12

**Example:**
```
Get recent analyst upgrades for Meta
```

## Usage Examples

Once configured with Claude Desktop or another MCP client, you can ask questions like:

- "What's the current price of Apple stock?"
- "Show me Tesla's quarterly revenue for the last year"
- "Get the latest news about Microsoft"
- "What are the dividend payments for Coca-Cola?"
- "Show me the institutional holders of NVIDIA"
- "Get Amazon's balance sheet"
- "What options are available for SPY?"
- "Show me recent analyst upgrades for Google"

## Development

### Setup Development Environment

```bash
# Clone the repository
git clone https://github.com/laxmimerit/yahoo-finance-mcp-server.git
cd yahoo-finance-mcp-server

# Install with development dependencies
uv pip install -e ".[dev]"
```

### Running Tests

```bash
pytest
```

### Code Formatting

```bash
black src/
ruff check src/
```

## Technical Details

- **Protocol**: Model Context Protocol (MCP)
- **Transport**: stdio
- **Data Source**: Yahoo Finance via yfinance library
- **Response Format**: JSON

## Requirements

- Python 3.10 or higher
- Dependencies:
  - fastmcp >= 0.3.0
  - yfinance >= 0.2.40
  - pandas >= 2.0.0

## Limitations

- Data is provided by Yahoo Finance and subject to their terms of service
- Real-time data may have delays depending on your subscription level
- Some data may not be available for all ticker symbols
- Intraday data is limited to the last 60 days

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Disclaimer

This software is for informational purposes only. It should not be considered financial advice. Always do your own research before making investment decisions.

## Support

If you encounter any issues or have questions:
- Open an issue on GitHub
- Check existing issues for solutions
- Consult the MCP documentation at https://modelcontextprotocol.io

## Acknowledgments

- Built with [FastMCP](https://github.com/jlowin/fastmcp)
- Data provided by [yfinance](https://github.com/ranaroussi/yfinance)
- Implements the [Model Context Protocol](https://modelcontextprotocol.io)