# Yahoo Finance MCP Server

A Model Context Protocol (MCP) server that integrates Yahoo Finance data with Claude Desktop, enabling powerful financial data analysis and research through natural language interactions.

## Overview

This project provides a comprehensive MCP server implementation that allows Claude to access real-time and historical financial data from Yahoo Finance. Whether you're analyzing stock performance, researching company fundamentals, or tracking market trends, this server makes financial data accessible through conversational AI.

## Features

The server exposes a comprehensive set of tools for financial data analysis:

### Stock Information Tools
- **Historical Price Data**: Retrieve OHLCV (Open, High, Low, Close, Volume) data with customizable periods and intervals
- **Stock Information**: Get comprehensive stock data including current price, market metrics, and company details
- **News Articles**: Access the latest news articles and market updates for any stock
- **Stock Actions**: View dividend history and stock split information

### Financial Statements
- **Income Statements**: Annual and quarterly income statements
- **Balance Sheets**: Annual and quarterly balance sheet data
- **Cash Flow Statements**: Annual and quarterly cash flow information

### Ownership & Holdings
- **Major Holders**: Top shareholders and their holdings
- **Institutional Holders**: Institutional ownership data
- **Mutual Fund Holders**: Mutual fund ownership information
- **Insider Transactions**: Recent insider trading activity

### Options Data
- **Expiration Dates**: Available options expiration dates for any stock
- **Options Chains**: Complete options chain data for calls and puts

### Analyst Information
- **Recommendations**: Current analyst recommendations and price targets
- **Upgrades/Downgrades**: Historical analyst rating changes

## Use Cases

### Example Queries You Can Make with Claude

**Stock Analysis:**
- "Show me the historical stock prices for AAPL over the last 6 months"
- "What are the key financial metrics for Tesla?"
- "Get the quarterly balance sheet for Microsoft"

### Market Research:
- "Get the latest news articles about Meta Platforms"
- "Show me the institutional holders of Apple stock"
- "What are the recent insider transactions for Tesla?"

### Options Analysis:
- "Get the options chain for SPY expiring in 30 days"
- "Show me call options for AAPL with expiration date 2024-06-21"

### Investment Research:
- "Compare the quarterly income statements of Amazon and Google"
- "Analyze the institutional ownership changes in Tesla over the past year"
- "Create a comprehensive financial health report for Microsoft"

## Requirements

- **Python**: 3.11 or higher
- **Dependencies**: See `pyproject.toml` for complete list
  - `mcp[cli]>=1.6.0` - Model Context Protocol framework
  - `yfinance>=0.2.62` - Yahoo Finance data library
  - `pandas` - Data manipulation and analysis
  - Additional dependencies for data processing

## Installation

### 1. Clone the Repository

```bash
git clone https://github.com/neupaneprashant/yahoo-finance-mcp.git
cd yahoo-finance-mcp
```

### 2. Install Dependencies

Install the project and its dependencies:

```bash
pip install -e .
```

Or if you prefer using a virtual environment:

```bash
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e .
```

### 3. Verify Installation

Run the setup verification script to ensure everything is installed correctly:

```bash
python3 test_setup.py
```

## Usage

### Testing the Server

You can test the server directly:

```bash
python3 server.py
```

This starts the MCP server in stdio mode, ready to accept MCP protocol messages.

### Integration with Claude Desktop

To use this server with Claude Desktop:

1. **Locate your Claude Desktop config file:**
   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - **Windows**: `%AppData%\Claude\claude_desktop_config.json`

2. **Open the config file:**
   ```bash
   # macOS
   code ~/Library/Application\ Support/Claude/claude_desktop_config.json
   
   # Windows
   code %AppData%\Claude\claude_desktop_config.json
   ```

3. **Add the server configuration:**

   For macOS:
   ```json
   {
     "mcpServers": {
       "yfinance": {
         "command": "/opt/anaconda3/bin/python3",
         "args": [
           "/absolute/path/to/yahoo-finance-mcp/server.py"
         ],
         "env": {
           "PYTHONPATH": "/absolute/path/to/yahoo-finance-mcp"
         }
       }
     }
   }
   ```

   For Windows:
   ```json
   {
     "mcpServers": {
       "yfinance": {
         "command": "python",
         "args": [
           "C:\\absolute\\path\\to\\yahoo-finance-mcp\\server.py"
         ],
         "env": {
           "PYTHONPATH": "C:\\absolute\\path\\to\\yahoo-finance-mcp"
         }
       }
     }
   }
   ```

   **Note**: Replace `/absolute/path/to/yahoo-finance-mcp` with the actual path to this repository on your system.

4. **Restart Claude Desktop** to load the new MCP server configuration.

5. **Verify the connection**: After restarting, the `yfinance` MCP server should appear in Claude Desktop, and you can start asking financial data questions.

## Project Structure

```
yahoo-finance-mcp/
├── server.py              # Main MCP server implementation
├── pyproject.toml         # Project configuration and dependencies
├── .pre-commit-config.yaml # Pre-commit hooks configuration
├── test_setup.py          # Setup verification script
├── setup_github.sh        # GitHub setup automation script
├── README.md              # This file
├── LICENSE                # MIT License
└── .gitignore            # Git ignore patterns
```

## Development

### Code Quality

This project uses pre-commit hooks to maintain code quality:

- **Black**: Code formatting (line length: 100)
- **isort**: Import sorting (compatible with Black)

To run the formatters manually:

```bash
# Format imports
python3 -m isort --profile=black --line-length=100 server.py

# Format code
python3 -m black --line-length=100 server.py
```

### Testing

Run the setup verification to ensure all dependencies are installed:

```bash
python3 test_setup.py
```

## Troubleshooting

### Server Not Appearing in Claude Desktop

1. **Check the config file syntax**: Ensure the JSON is valid
2. **Verify the Python path**: Make sure the path to `python3` is correct
3. **Check file permissions**: Ensure the server.py file is executable
4. **Review Claude Desktop logs**: Check for error messages in the console

### Import Errors

If you encounter import errors:

```bash
# Verify dependencies are installed
python3 -c "import yfinance, pandas, mcp; print('All dependencies available')"

# Reinstall if needed
pip install -e .
```

## Contributing

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

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- Built using the [Model Context Protocol](https://modelcontextprotocol.io/) framework
- Financial data provided by [Yahoo Finance](https://finance.yahoo.com/) via the `yfinance` library
- Thanks to the open-source community for the excellent tools and libraries

---

**Author**: Prashant Neupane  
**Repository**: [github.com/neupaneprashant/yahoo-finance-mcp](https://github.com/neupaneprashant/yahoo-finance-mcp)