yfin-mcp - Yahoo Finance MCP Server

Enhanced fork of yahoo-finance-mcp by Alex2Yang97
With intelligent pagination, caching, and LLM-optimized responses

<div align="right"> <a href="README.md">English</a> | <a href="README.zh.md">中文</a> </div>

A high-performance Model Context Protocol (MCP) server that provides comprehensive financial data from Yahoo Finance with intelligent pagination, caching, and LLM-optimized responses.

---

🙏 Attribution & Motivation

Original Work

This project is built upon the excellent foundation of yahoo-finance-mcp created by Alex2Yang97. The original implementation provides a comprehensive set of tools for accessing Yahoo Finance data through the Model Context Protocol.

Why These Enhancements?

While using the original implementation with LLM agents (Claude, ChatGPT, etc.), I encountered critical limitations:

Problem 1: Context Window Overflow

• Historical stock data with period="max" could return thousands of rows
• Option chains for popular stocks contained hundreds of contracts
• LLM context windows (typically 200K tokens) would overflow
• Responses would be truncated, losing critical data

Problem 2: No Data Persistence

• Large datasets couldn't be saved for offline analysis
• Repeated queries wasted API calls and time
• No way to export data for use in other tools

Problem 3: Poor LLM Readability

• JSON responses were hard for LLMs to parse when truncated
• No clear navigation guidance for paginated data
• Cache status was invisible to the LLM

Solution: Pagination, Caching & Export

This fork adds three key enhancements:

1. Token-Based Pagination (6,000 token limit per page)

   • Prevents context window overflow
   • Clear navigation guidance for LLMs
   • Dynamic page sizing based on data complexity

2. Intelligent Caching (TTL: 5min-1hr)

   • Reduces redundant API calls by 50-80%
   • Sub-millisecond response times for cached data
   • Automatic cache invalidation based on data volatility

3. JSON Export (File Download)

   • Save full datasets for offline analysis
   • Export to Excel, databases, or other tools
   • Preserve complete data without pagination

Credit Where Credit is Due

Original Author: Alex2Yang97 deserves full credit for:

• ✅ Complete Yahoo Finance API integration
• ✅ All 9 MCP tools implementation
• ✅ Robust error handling
• ✅ Comprehensive documentation

This Fork Adds: Pagination, caching, and export features to make the server production-ready for LLM agents handling large financial datasets.

Demo

MCP Tools

The server exposes the following tools through the Model Context Protocol:

Stock Information

Tool	Description
get_historical_stock_prices	Get historical OHLCV data for a stock with customizable period and interval
get_stock_info	Get comprehensive stock data including price, metrics, and company details
get_yahoo_finance_news	Get latest news articles for a stock
get_stock_actions	Get stock dividends and splits history

Financial Statements

Tool	Description
get_financial_statement	Get income statement, balance sheet, or cash flow statement (annual/quarterly)
get_holder_info	Get major holders, institutional holders, mutual funds, or insider transactions

Options Data

Tool	Description
get_option_expiration_dates	Get available options expiration dates
get_option_chain	Get options chain for a specific expiration date and type (calls/puts)

Analyst Information

Tool	Description
get_recommendations	Get analyst recommendations or upgrades/downgrades history

Real-World Use Cases

With this MCP server, you can use Claude to:

Stock Analysis

• Price Analysis: "Show me the historical stock prices for AAPL over the last 6 months with daily intervals."
• Financial Health: "Get the quarterly balance sheet for Microsoft."
• Performance Metrics: "What are the key financial metrics for Tesla from the stock info?"
• Trend Analysis: "Compare the quarterly income statements of Amazon and Google."
• Cash Flow Analysis: "Show me the annual cash flow statement for NVIDIA."

Market Research

• News Analysis: "Get the latest news articles about Meta Platforms."
• Institutional Activity: "Show me the institutional holders of Apple stock."
• Insider Trading: "What are the recent insider transactions for Tesla?"
• Options Analysis: "Get the options chain for SPY with expiration date 2024-06-21 for calls."
• Analyst Coverage: "What are the analyst recommendations for Amazon over the last 3 months?"

Investment Research

• "Create a comprehensive analysis of Microsoft's financial health using their latest quarterly financial statements."
• "Compare the dividend history and stock splits of Coca-Cola and PepsiCo."
• "Analyze the institutional ownership changes in Tesla over the past year."
• "Generate a report on the options market activity for Apple stock with expiration in 30 days."
• "Summarize the latest analyst upgrades and downgrades in the tech sector over the last 6 months."

Requirements

• Python 3.11 or higher
• Dependencies as listed in pyproject.toml, including:
  • mcp
  • yfinance
  • pandas
  • pydantic
  • and other packages for data processing

Installation

From PyPI (Recommended)

Install the package directly from PyPI:

pip install yfin-mcp

From Source

1. Clone this repository:

   git clone https://github.com/fritzprix/yahoo-finance-mcp.git
   cd yahoo-finance-mcp
   

2. Create and activate a virtual environment and install dependencies:

   uv venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   uv pip install -e .
   

Usage

Integration with Claude for Desktop

After installing the package, you can integrate it with Claude for Desktop:

1. Install the package (if not already installed):

   pip install yfin-mcp
   

2. Configure Claude Desktop:

   • MacOS: Edit ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: Edit %APPDATA%\Claude\claude_desktop_config.json

3. Add the server configuration:

   Using uvx (Recommended - No installation needed):

   {
     "mcpServers": {
       "yfinance": {
         "command": "uvx",
         "args": ["yfin-mcp"]
       }
     }
   }
   

   Using Python directly (if installed via pip):

   {
     "mcpServers": {
       "yfinance": {
         "command": "python",
         "args": ["-m", "yfin_mcp"]
       }
     }
   }
   

   For development/source installation:

   • macOS:

     {
       "mcpServers": {
         "yfinance": {
           "command": "uv",
           "args": [
             "--directory",
             "/ABSOLUTE/PATH/TO/yahoo-finance-mcp",
             "run",
             "server.py"
           ]
         }
       }
     }
     

   • Windows:

     {
       "mcpServers": {
         "yfinance": {
           "command": "uv",
           "args": [
             "--directory",
             "C:\\ABSOLUTE\\PATH\\TO\\yahoo-finance-mcp",
             "run",
             "server.py"
           ]
         }
       }
     }
     

4. Restart Claude for Desktop

Development Mode

For testing with MCP Inspector:

# From source
uv run yfin-mcp

# Or if installed via pip
python -m yfin_mcp

Publishing to PyPI

To build and publish the package, use the provided scripts. You can optionally provide an argument to bump the version:

Windows

# Just build and publish current version
publish_package.bat

# Bump version and then publish
publish_package.bat patch
publish_package.bat minor
publish_package.bat major

macOS/Linux

chmod +x publish_package.sh

# Just build and publish current version
./publish_package.sh

# Bump version and then publish
./publish_package.sh patch
./publish_package.sh minor
./publish_package.sh major

[!NOTE] The scripts will build the package into the dist/ directory and then use twine to upload it. Ensure you have your PyPI credentials configured in ~/.pypirc (or %HOME%\.pypirc on Windows) or set the TWINE_PASSWORD environment variable.

Troubleshooting

[ERROR] os error 32: Process cannot access the file

If you see this error when running publish_package.bat or uv build, it means the MCP server is still running and locking the executable.

1. Close Claude Desktop or any app using the yfinance MCP server.
2. Stop any running MCP Inspector instances.
3. If the error persists, manually kill the processes:

   taskkill /F /IM yfin-mcp.exe /T
   taskkill /F /IM python.exe /T
   

License

MIT License

Original Work: Copyright (c) 2025 AlexYoung
Fork Enhancements: Copyright (c) 2026 SKTelecom

This project maintains the MIT License from the original yahoo-finance-mcp project. All enhancements (pagination, caching, export) are also released under MIT License.

See LICENSE file for full details.