yahoo-fianace-mcp
The Yahoo Finance MCP Server allows users to access Yahoo Finance data using various functions from the `yfinance` library. It is set up to work with MCP clients and offers a range of tools for querying financial information efficiently.
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. - On macOS/Linux:
-
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.