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:

source .venv/bin/activate

source .venv/Scripts/activate

.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.

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