yahoo-fianace-mcp

Certified

Yahoo Finance MCP Server

This project provides a Model Context Protocol (MCP) server that exposes various functions from the yfinance library as individual tools. This allows an MCP client (like Claude Desktop) to query Yahoo Finance data.

Prerequisites

• Python: Ensure you have Python installed (Python 3.8+ recommended).
• uv: This project uses uv for environment and package management. If you don't have it, install it following the instructions here: https://github.com/astral-sh/uv

Setup

1. Clone the repository:

   git clone git@github.com:a05031113/yahoo-fianace-mcp.git
   cd yahoo-finance # Or your repository directory name
   

2. Create a virtual environment: It's highly recommended to use a virtual environment. Create one using uv:

   uv venv
   

   This will create a .venv directory.

3. Activate the virtual environment:

   • On macOS/Linux:

     source .venv/bin/activate
     

   • On Windows (Git Bash/WSL):

     source .venv/Scripts/activate
     

   • On Windows (Command Prompt/PowerShell):

     .venv\Scripts\activate
     

   You should see (.venv) at the beginning of your terminal prompt.

4. Install dependencies: Install the required Python packages using uv:

   uv pip install -r requirements.txt
   

Running the Server

This server communicates via standard input/output (stdio) as expected by MCP. To run the server, simply execute the main.py script using the Python interpreter from your activated virtual environment:

python main.py

The server will start and print log messages to standard error (stderr), waiting for JSON-RPC requests on standard input (stdin).

You would typically configure your MCP client (e.g., in its settings JSON file) to run this command:

{
  "mcpServers": {
    "yahoo_finance_engine": {
      "command": "/path/to/your/yahoo-finance/.venv/bin/python", // Adjust path accordingly
      "args": [
        "/path/to/your/yahoo-finance/main.py" // Adjust path accordingly
      ]
    }
    // ... other servers
  }
}

The MCP client will then manage starting and communicating with this server process.

Available Tools

The server exposes the public methods of the YahooFinance class (defined in src/tool.py) as individual MCP tools. These include (but are not limited to):

• get_current_stock_price(symbol: str)
• get_stock_price_by_date(symbol: str, date: str)
• get_stock_price_date_range(symbol: str, start_date: str, end_date: str)
• get_historical_stock_prices(symbol: str, period: str = "1mo", interval: str = "1d")
• get_dividends(symbol: str)
• get_income_statement(symbol: str, freq: str = "yearly")
• get_cashflow(symbol: str, freq: str = "yearly")
• get_balance_sheet(symbol: str, freq: str = "yearly")
• get_earning_dates(symbol: str, limit: int = 12)
• get_news(symbol: str)
• get_company_info(symbol: str)
• get_splits(symbol: str)
• get_recommendations(symbol: str)
• get_analyst_price_targets(symbol: str)
• get_major_holders(symbol: str)
• get_institutional_holders(symbol: str)
• get_mutualfund_holders(symbol: str)
• get_option_expiration_dates(symbol: str)
• get_option_chain(symbol: str, date: str)
• get_sustainability(symbol: str)

Refer to the docstrings within main.py or src/tool.py for details on each tool's parameters.