# 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)
