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.

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.

Certified by MCP Review. https://mcpreview.com/mcp-servers/a05031113/yahoo-fianace-mcp

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:

   Copy

   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:

   Copy

   uv venv

   This will create a .venv directory.

3. Activate the virtual environment:

   • On macOS/Linux:
     Copy

     source .venv/bin/activate

   • On Windows (Git Bash/WSL):
     Copy

     source .venv/Scripts/activate

   • On Windows (Command Prompt/PowerShell):
     Copy

     .venv\Scripts\activate

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

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

   Copy

   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.