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.

• Stock Data — Company info, financials, valuation metrics, dividends, and trading data
• 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

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.

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.

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

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

Get top-ranked financial entities within a market sector.

Returns: JSON array of top entities with relevant metrics.

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

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.

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

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.

Fetch available option expiration dates for a stock.

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

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)

1. Install uv
2. Add the following to your MCP client configuration:

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

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

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.

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

• Python ≥ 3.12
• uv package manager

uv sync --extra dev

uv run ruff check .
uv run ruff format .

uv run ty check src tests

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

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

Made with contrib.rocks.

This project is licensed under the MIT License.