MCP Yahoo Finance

MCP Yahoo Finance

MCP Yahoo Finance is a Model Context Protocol (MCP) server. It gets data from Yahoo Finance. You can use it to get stock prices, company data, past prices, financial reports, news, analyst ratings, earnings dates, dividends, and options data.

This project is in early development. Tool names and response fields can change between releases.

Install

You can run mcp-yahoo-finance without a separate install. Use uvx.

Use pip

pip install mcp-yahoo-finance

Use Git

Clone the repository. Then install the development environment:

git clone [email protected]:maxscheijen/mcp-yahoo-finance.git
cd mcp-yahoo-finance
uv sync

Configure

Claude Desktop

Add this entry to your claude_desktop_config.json file:

{
    "mcpServers": {
        "yahoo-finance": {
            "command": "uvx",
            "args": ["mcp-yahoo-finance"]
        }
    }
}

You can also use Docker. Replace IMAGE with the Docker image name:

{
    "mcpServers": {
        "yahoo-finance": {
            "command": "docker",
            "args": ["run", "-i", "--rm", "IMAGE"]
        }
    }
}

VS Code

Add this entry to your .vscode/mcp.json file:

{
    "servers": {
        "yahoo-finance": {
            "command": "uvx",
            "args": ["mcp-yahoo-finance"]
        }
    }
}

Example questions

You can ask questions like these:

1. "What is the stock price of Apple?"
2. "Give me a rich quote for AAPL with the previous close, intraday range, and market status."
3. "Show me the company overview for Nvidia."
4. "What is the difference in stock price between Apple and Google?"
5. "How much did the stock price of Apple change between 2024-01-01 and 2025-01-01?"
6. "What are the available options expiration dates for AAPL?"
7. "Show me the options chain for AAPL expiring on 2024-01-19."
8. "What are the call and put options for Tesla?"

Response data

Tools return data in JSON format. This is an example of a rich quote:

{
  "symbol": "AAPL",
  "currentPrice": 243.5822,
  "previousClose": 241.33,
  "absoluteChange": 2.2522,
  "percentChange": 0.9331,
  "open": 242.1,
  "dayHigh": 244.2,
  "dayLow": 241.9,
  "volume": 45678901,
  "marketStatus": "REGULAR",
  "currency": "USD",
  "exchange": "NMS",
  "timestamp": "2025-01-02T15:30:00+00:00",
  "source": {
    "provider": "Yahoo Finance",
    "endpoint": "info",
    "fetchedAt": "2025-01-02T15:30:01+00:00"
  }
}

Errors use the same format for all tools. An error includes an error code and a message:

{
  "error": {
    "code": "NO_DATA",
    "message": "No historical data found for AAPL"
  }
}

Historical and table results keep the column names from the data source. Dates use the YYYY-MM-DD format. The server does not show the time zone used by Yahoo Finance.

Historical price tools return adjusted prices by default. Adjusted prices include changes from stock splits and dividends. To get prices without these changes, set adjusted to false in get_historical_stock_prices.

Date searches include both the start date and the end date. If a date is a weekend or market holiday, there may be no price data for that date. In that case, the tool returns a NO_DATA error.

If quote or company data is missing, its value is null. The news tool returns 10 articles by default. It can return up to 100 articles. It includes the title, URL, publisher, thumbnail, related stock symbols, and publish time. The publish time uses UTC and the ISO 8601 format. You can set start_date and end_date to filter news. The filter includes both dates.

Recommendation, earnings, dividend, financial report, and options tools use a top-level symbol field. They return data from Yahoo Finance when that data is available.

Available tools

Use Yahoo Finance ticker symbols for symbol values. Examples are AAPL and MSFT.

Tool	Purpose
get_current_stock_price	Gets the current stock price and quote data.
get_rich_quote	Gets a quote with price, price change, trading range, market status, and source data.
get_company_overview	Gets a company profile with its sector, industry, market value, website, employee count, description, and source data.
get_symbol_comparison	Compares current quotes for up to 20 symbols.
get_performance_analysis	Compares returns, moving averages, volatility, drawdown, benchmark returns, and correlation for multiple symbols.
get_stock_price_by_date	Gets the adjusted closing price for one trading date.
get_stock_price_date_range	Gets adjusted closing prices for a date range.
get_historical_stock_prices	Gets past prices for a period and time interval.
get_dividends	Gets past dividend payments.
get_stock_splits	Gets past stock splits.
get_capital_gains	Gets capital-gains payments.
get_upcoming_dividends	Gets future dividend dates and rates.
get_earnings_analytics	Gets earnings results and estimates.
get_income_statement	Gets an income statement by year, quarter, or trailing period.
get_cashflow	Gets a cash flow statement by period.
get_earning_dates	Gets past and future earnings dates.
get_news	Gets Yahoo Finance news. You can set date filters.
get_recommendations	Gets analyst recommendations.
get_option_expiration_dates	Gets available option expiration dates.
get_option_chain	Gets calls and puts for one expiration date. You can filter by strike price, moneyness, liquidity, spread, type, and number of results.
get_option_summary	Gets implied volatility, open interest, volume, put/call ratios, and max pain for one expiration date.

Performance calculations

Performance analysis uses closing prices adjusted for stock splits and dividends.

Total return is (last close / first close) - 1.

Annual volatility is the standard deviation of daily returns multiplied by sqrt(252).

Maximum drawdown is the largest fall from a previous high.

The tool calculates correlation from daily returns on dates shared by the symbols. This lets it compare symbols that have different trading calendars.

Develop locally

Run uv sync to install the locked development environment. Then run these commands:

uv run pytest
uv run ruff check .
uv run ruff format --check .
uv build

You can also use these Makefile commands:

make test
make lint
make docker-build

The tests use mock Yahoo Finance data. They do not make live requests to Yahoo Finance.

Build the Docker image

Run this command:

docker build -t mcp-yahoo-finance .

Test with MCP Inspector

Run this command:

npx @modelcontextprotocol/inspector uv run mcp-yahoo-finance

Yahoo Finance limits

Yahoo Finance is a third-party data source. Its data can be late, incomplete, or unavailable. This project does not give investment advice. It does not guarantee that the data is correct, complete, or up to date. Check important data with an authoritative source before you use it.