Skip to main content
Glama
MCP Yahoo Finance

MCP Yahoo Finance

by maxscheijen

MCP Yahoo Finance

PyPI - Version PyPI - Python Version PyPI - License

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 git@github.com:maxscheijen/mcp-yahoo-finance.git
cd mcp-yahoo-finance
uv sync

Related MCP server: MCP Yahoo Finance

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_portfolio_analysis

Calculates position values and allocations from quantities, weighted portfolio returns from weights, or per-symbol watchlist metrics without sizing.

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.

get_portfolio_analysis accepts symbols, start_date, and end_date, plus either quantities, weights, or neither. Quantities report current market value and value-based allocations. Weights are normalized and applied to daily adjusted returns. Omitting both quantities and weights selects watchlist mode and returns per-symbol metrics without portfolio totals. Historical performance uses adjusted close prices; current market values use Yahoo's current quote. Portfolio totals require every available position to report the same currency. Missing history or quotes are omitted and described in errors. Unequal trading calendars use forward-filled closes for aggregate daily returns.

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.

Available Tools

21 tools
get_capital_gainsB

Get normalized capital-gains distributions for a symbol.

Inputs: symbol (required).

get_cashflowB

Get the cashflow statement for a given stock symbol.

Inputs: symbol (required), freq.

get_company_overviewC

Get a normalized company overview for one stock symbol.

Inputs: symbol (required).

get_current_stock_priceC

Get the current stock price based on stock symbol.

Inputs: symbol (required).

get_dividendsB

Get normalized dividend history for a given stock symbol.

Inputs: symbol (required).

get_earning_datesB

Get recent and upcoming earnings dates.

Inputs: symbol (required), limit.

get_earnings_analyticsC

Get earnings surprise history and analyst estimate history.

Inputs: symbol (required), limit.

get_historical_stock_pricesC

Get historical stock prices for a given stock symbol.

Inputs: symbol (required), period, adjusted, interval.

get_income_statementC

Get the income statement for a given stock symbol.

Inputs: symbol (required), freq.

get_newsB

Get normalized, bounded news for a stock symbol.

Inputs: symbol (required), limit, end_date, start_date.

get_option_chainC

Get a filtered, bounded option chain for one expiration date.

Inputs: symbol (required), expiration_date (required), limit, moneyness, +6 more.

get_option_expiration_datesB

Get available option expiration dates for a stock symbol.

Inputs: symbol (required).

get_option_summaryB

Summarize option interest, volume, volatility, ratios, and max pain.

Inputs: symbol (required), expiration_date (required), limit.

get_performance_analysisC

Analyze adjusted performance for multiple symbols over a date range.

Inputs: symbols (required), end_date (required), start_date (required), limit, +1 more.

get_recommendationsC

Get analyst recommendations for a given symbol.

Inputs: symbol (required).

get_rich_quoteC

Get a normalized quote snapshot for one stock symbol.

Inputs: symbol (required).

get_stock_price_by_dateB

Get the stock price for a given stock symbol on a specific date.

Inputs: date (required), symbol (required).

get_stock_price_date_rangeC

Get stock prices for a symbol over an inclusive date range.

Inputs: symbol (required), end_date (required), start_date (required).

get_stock_splitsB

Get normalized stock split history for a symbol.

Inputs: symbol (required).

get_symbol_comparisonB

Compare current quote data for multiple stock symbols.

Inputs: symbols (required).

get_upcoming_dividendsC

Get upcoming dividend dates and rates when Yahoo provides them.

Inputs: symbol (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 21 tools

    Disambiguation3/5

    Several price-related tools overlap significantly: get_current_stock_price, get_rich_quote, get_stock_price_by_date, get_stock_price_date_range, and get_historical_stock_prices all return price data with only subtle scope differences. Other tool groups (options, earnings, dividends) are more clearly distinct, but the price cluster will likely cause misselection.

    Naming Consistency5/5

    All tools follow a consistent get_<noun> snake_case pattern. The vocabulary varies slightly (e.g., stock_price vs. symbol), but the verb and casing convention is uniform throughout.

    Tool Count3/5

    With 21 tools, the set is on the heavy side for a single finance data server. Many tools are justified, but the price-related group feels inflated with overlapping endpoints.

    Completeness4/5

    The surface covers quotes, historical prices, financial statements, options, earnings, dividends, splits, news, and recommendations. A balance sheet tool is missing, and some advanced Yahoo Finance capabilities (e.g., insider transactions, fund data) are absent, but core workflows are well supported.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      A Model Context Protocol server providing real-time stock data and options analysis through Yahoo Finance, enabling LLMs to access market data, analyze stocks, and evaluate options strategies.
      3
      27
      MIT
    • A
      license
      C
      quality
      Not graded
      maintenance
      A Model Context Protocol server that provides tools for interacting with Yahoo Finance, allowing users to retrieve stock prices, company information, and perform financial data comparisons.
      11
      MIT
    • A
      license
      C
      quality
      D
      maintenance
      A Model Context Protocol server providing comprehensive financial data from Yahoo Finance, allowing users to retrieve detailed stock information, financial statements, options data, and market news.
      34
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      A Model Context Protocol server providing comprehensive access to Yahoo Finance data through the yahooquery library, enabling AI assistants to retrieve stock prices, financial statements, market data, and company analytics.
      12
      MIT