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

Clone the repository:

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

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

Setup

Clone the repository:

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

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.

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.

Install dependencies: Install the required Python packages using uv:

uv pip install -r requirements.txt

Running the Server

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.