Yahoo Finance MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with access to Yahoo Finance data via yfinance. Query stock information, financial news, sector rankings, and generate professional financial charts — all from your AI chat.

Features

• Stock Data — Company info, financials, valuation metrics, dividends, and trading data
• Analyst Data — Consensus targets, estimate/revision trends, recommendation history, and firm-level actions
• Financial Statements — Income statement and balance sheet with historical data (EBIT, Invested Capital, etc.)
• Financial News — Recent news articles and press releases for any ticker
• Search — Find stocks, ETFs, and news across Yahoo Finance
• Sector Rankings — Top ETFs, mutual funds, companies, growth leaders, and top performers by sector
• Price History — Historical OHLCV data as markdown tables or professional charts
• Chart Generation — Candlestick, VWAP, and volume profile charts returned as WebP images
• Options Data — Option chains with calls, puts, strike prices, IV, and expiration dates
• Ownership Data — Major holders, institutional investors, mutual fund holders, and insider transactions
• Fund Look-Through — ETF and mutual-fund holdings, asset classes, sectors, ratings, and operating details
• Screeners — Predefined, equity, mutual-fund, and ETF query trees

Tools

`yfinance_get_ticker_info`

Retrieve comprehensive stock data including company info, financials, trading metrics, and governance data.

Returns: JSON object with company details, price data, valuation metrics, trading info, dividends, financials, and performance indicators.

`yfinance_get_analyst_price_targets`

Fetch the current price and analyst consensus price targets for a stock.

Returns: JSON object with `current`, `low`, `high`, `mean`, and `median` price fields. Analyst coverage and available fields vary by symbol.

`yfinance_get_analyst_estimates`

Fetch analyst consensus estimates, revision momentum, recommendations, growth estimates, and earnings history.

Returns: Named arrays for available sections plus `_metadata` containing per-section row counts, truncation status, unavailable sections, and failed sections. A failure in one section does not discard successfully fetched sections.

`yfinance_get_upgrades_downgrades`

Fetch analyst upgrades, downgrades, initiations, reiterations, and price-target changes, newest first.

Returns: JSON object containing `upgrades_downgrades` records and `_metadata` with row counts and truncation status. Records can include:

• `GradeDate`: Date and time of the analyst action
• `Firm`: Analyst firm name
• `ToGrade` and `FromGrade`: New and previous ratings
• `Action`: Rating action
• `priceTargetAction`: Price-target action such as `Raises`, `Lowers`, or `Maintains`
• `currentPriceTarget` and `priorPriceTarget`: New and previous price targets

Available fields vary by symbol and analyst action.

`yfinance_get_ticker_news`

Fetch recent news articles and press releases for a specific stock.

Returns: JSON array of news items with title, summary, publication date, provider, URL, and thumbnail.

`yfinance_search`

Search Yahoo Finance for stocks, ETFs, and news articles.

Returns: Matching quotes and/or news results depending on `search_type`.

`yfinance_get_top`

Get top-ranked financial entities within a market sector.

Returns: JSON array of top entities with relevant metrics.

Supported Sectors

`Basic Materials`, `Communication Services`, `Consumer Cyclical`, `Consumer Defensive`, `Energy`, `Financial Services`, `Healthcare`, `Industrials`, `Real Estate`, `Technology`, `Utilities`

`yfinance_screen`

Run Yahoo Finance screeners using either predefined screener keys or custom query trees.

Returns: JSON screener response from Yahoo Finance, typically including quote rows and metadata.

Custom equity screener example:

{
  "query_type": "equity",
  "query": {
    "operator": "and",
    "operands": [
      { "operator": "gt", "operands": ["percentchange", 3] },
      { "operator": "eq", "operands": ["region", "us"] },
      { "operator": "gte", "operands": ["intradayprice", 5] },
      { "operator": "gt", "operands": ["dayvolume", 500000] }
    ]
  },
  "sort_field": "percentchange",
  "sort_asc": false,
  "size": 50
}

Custom ETF screener example:

{
  "query_type": "etf",
  "query": {
    "operator": "and",
    "operands": [
      { "operator": "eq", "operands": ["categoryname", "Large Blend"] },
      { "operator": "lte", "operands": ["annualreportnetexpenseratio", 0.2] }
    ]
  },
  "sort_field": "fundnetassets",
  "sort_asc": false,
  "size": 25
}

`yfinance_screen_gappers`

Run a purpose-built custom screener for opening-session bullish gappers.

Returns: JSON screener response from Yahoo Finance.

`yfinance_get_price_history`

Fetch historical price data and optionally generate technical analysis charts.

Chart types:

Returns:

• Without `chart_type`: Markdown table with Date, Open, High, Low, Close, Volume, Dividends, and Stock Splits columns.
• With `chart_type`: Base64-encoded WebP image for efficient token usage.

`yfinance_get_financials`

Fetch financial statements (income statement, balance sheet, and cash flow) with historical data.

Returns: JSON object with income statement, balance sheet, and cash flow data for each reporting period.

• Income Statement fields: EBIT, Net Income, Tax Provision, Pretax Income, Interest Expense, Total Revenue, Operating Income, EBITDA, Normalized Income
• Balance Sheet fields: Stockholders Equity, Total Debt, Cash And Cash Equivalents, Invested Capital, Net Debt, Total Assets, Total Liabilities Net Minority Interest, Net Tangible Assets, Tangible Book Value
• Cash Flow fields: Operating Cash Flow, Free Cash Flow, Capital Expenditure, Net Income From Continuing Operations, Depreciation And Amortization, Change In Working Capital, Cash Dividends Paid

`yfinance_get_holders`

Fetch major holders, institutional holders, mutual fund holders, and insider data.

Returns: JSON object with:

• `major_holders` — Aggregated breakdown where each row has an `index` label (e.g. `insidersPercentHeld`, `institutionsPercentHeld`, `institutionsFloatPercentHeld`, `institutionsCount`) and a `Value`
• `institutional_holders` — Institutional investors; records typically include fields such as `Date Reported`, `Holder`, `Shares`, `Value`, `pctChange`, `pctHeld`
• `mutualfund_holders` — Mutual fund holders; records typically include fields similar to institutional holders
• `insider_transactions` — Recent insider trades; records typically include fields such as `Shares`, `Value`, `Insider`, `Position`, `Transaction`, `Start Date`, `Ownership`
• `insider_purchases` — Six-month summary where each row describes a category (Purchases, Sales, Net Shares, etc.); records typically include fields such as `Insider Purchases Last 6m`, `Shares`, `Trans`
• `insider_roster` — Known insiders; records typically include fields such as `Name`, `Position`, `Shares Owned Directly`, `Most Recent Transaction`, `Latest Transaction Date`
• `_metadata` — Row limit metadata with `max_rows` and per-section `total_rows`, `returned_rows`, and `truncated`

Holder sections are limited to 10 rows by default to keep responses concise. Pass `max_rows: 0` when you need the complete holder datasets. Field names for holder-related datasets are provided by `yfinance` and may vary by ticker, data availability, and `yfinance` version.

`yfinance_get_fund_data`

Fetch ETF or mutual-fund portfolio composition and operating details.

Returns: Available fund sections plus `_metadata` with row limits, per-section truncation, unavailable sections, and failed sections. The mix of sections depends on the fund; for example, equity funds and bond funds expose different portfolio breakdowns.

`yfinance_get_option_dates`

Fetch available option expiration dates for a stock.

Returns: JSON array of expiration dates in YYYY-MM-DD format.

`yfinance_get_option_chain`

Fetch option chain data (calls and puts) for a stock with available strike prices.

Returns: JSON object keyed by expiration date, with calls and/or puts data including:

• `contractSymbol`: Option contract identifier
• `strike`: Strike price
• `lastPrice`: Last traded price
• `bid`/`ask`: Bid and ask prices
• `volume`: Trading volume
• `openInterest`: Open interest
• `impliedVolatility`: IV
• `inTheMoney`: Whether option is ITM
• `contractSize`: Contract size (REGULAR)
• `currency`: Currency (USD)

Usage

Via uv (recommended)

1. Install uv

2. Add the following to your MCP client configuration:

{
  "mcpServers": {
    "yfmcp": {
      "command": "uvx",
      "args": ["yfmcp@latest"]
    }
  }
}

Via Docker

{
  "mcpServers": {
    "yfmcp": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "narumi/yfinance-mcp"]
    }
  }
}

From Source

1. Clone the repository and install dependencies:

git clone https://github.com/narumiruna/yfinance-mcp.git
cd yfinance-mcp
uv sync

2. Add the following to your MCP client configuration:

{
  "mcpServers": {
    "yfmcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/yfinance-mcp",
        "yfmcp"
      ]
    }
  }
}

Replace `/path/to/yfinance-mcp` with the actual path to your cloned repository.

Testing with Codex CLI

This repository includes `.codex/config.toml`, which registers the local `yfmcp` MCP server for Codex CLI using `uv run yfmcp`. After cloning the repository and running `uv sync`, open Codex CLI from the repository root and try prompts such as:

Show VOO ticker info
Show VOO price history for the last 5 days
Find the ticker symbol for Toyota
Get AAPL option expiration dates

Development

Prerequisites

• Python ≥ 3.12
• uv package manager

Setup

uv sync --extra dev

Lint & Format

uv run ruff check .
uv run ruff format .

Type Check

uv run ty check src tests

Test

uv run pytest -v -s --cov=src tests

Demo Chatbot

See the demo chatbot in its dedicated repository: yfinance-mcp-demo

Contributors

Made with contrib.rocks.

License

This project is licensed under the MIT License.