{
  "markdown": "# Yahoo Finance MCP Server\n\n<!-- mcp-name: io.github.narumiruna/yfinance-mcp -->\n\n[![PyPI version](https://img.shields.io/pypi/v/yfmcp)](https://pypi.org/project/yfmcp/)\n[![Python](https://img.shields.io/pypi/pyversions/yfmcp.svg)](https://pypi.org/project/yfmcp/)\n[![CI](https://github.com/narumiruna/yfinance-mcp/actions/workflows/python.yml/badge.svg)](https://github.com/narumiruna/yfinance-mcp/actions/workflows/python.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nA [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that provides AI assistants with access to Yahoo Finance data via [yfinance](https://github.com/ranaroussi/yfinance). Query stock information, financial news, sector rankings, and generate professional financial charts — all from your AI chat.\n\n## Features\n\n- **Stock Data** — Company info, financials, valuation metrics, dividends, and trading data\n- **Analyst Data** — Consensus targets, estimate/revision trends, recommendation history, and firm-level actions\n- **Financial Statements** — Income statement and balance sheet with historical data (EBIT, Invested Capital, etc.)\n- **Financial News** — Recent news articles and press releases for any ticker\n- **Search** — Find stocks, ETFs, and news across Yahoo Finance\n- **Sector Rankings** — Top ETFs, mutual funds, companies, growth leaders, and top performers by sector\n- **Price History** — Historical OHLCV data as markdown tables or professional charts\n- **Chart Generation** — Candlestick, VWAP, and volume profile charts returned as WebP images\n- **Options Data** — Option chains with calls, puts, strike prices, IV, and expiration dates\n- **Ownership Data** — Major holders, institutional investors, mutual fund holders, and insider transactions\n- **Fund Look-Through** — ETF and mutual-fund holdings, asset classes, sectors, ratings, and operating details\n- **Screeners** — Predefined, equity, mutual-fund, and ETF query trees\n\n## Tools\n\n### `yfinance_get_ticker_info`\n\nRetrieve comprehensive stock data including company info, financials, trading metrics, and governance data.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `symbol` | string | Yes | Stock ticker symbol (e.g. `AAPL`, `GOOGL`, `MSFT`) |\n\n**Returns:** JSON object with company details, price data, valuation metrics, trading info, dividends, financials, and performance indicators.\n\n### `yfinance_get_analyst_price_targets`\n\nFetch the current price and analyst consensus price targets for a stock.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `symbol` | string | Yes | Stock ticker symbol (e.g. `AAPL`, `GOOGL`, `MSFT`) |\n\n**Returns:** JSON object with `current`, `low`, `high`, `mean`, and `median` price fields. Analyst coverage and available fields vary by symbol.\n\n### `yfinance_get_analyst_estimates`\n\nFetch analyst consensus estimates, revision momentum, recommendations, growth estimates, and earnings history.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `symbol` | string | Yes | Stock ticker symbol |\n| `sections` | array | No | Any of `recommendations`, `earnings_estimate`, `revenue_estimate`, `eps_trend`, `eps_revisions`, `earnings_history`, or `growth_estimates`. Omit for all sections |\n| `max_rows` | number | No | Maximum rows per section. Default: `12`. Use `0` for all rows |\n\n**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.\n\n### `yfinance_get_upgrades_downgrades`\n\nFetch analyst upgrades, downgrades, initiations, reiterations, and price-target changes, newest first.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `symbol` | string | Yes | Stock ticker symbol |\n| `max_rows` | number | No | Maximum actions to return. Default: `25`. Use `0` to return all rows |\n\n**Returns:** JSON object containing `upgrades_downgrades` records and `_metadata` with row counts and truncation status. Records can include:\n\n- `GradeDate`: Date and time of the analyst action\n- `Firm`: Analyst firm name\n- `ToGrade` and `FromGrade`: New and previous ratings\n- `Action`: Rating action\n- `priceTargetAction`: Price-target action such as `Raises`, `Lowers`, or `Maintains`\n- `currentPriceTarget` and `priorPriceTarget`: New and previous price targets\n\nAvailable fields vary by symbol and analyst action.\n\n### `yfinance_get_ticker_news`\n\nFetch recent news articles and press releases for a specific stock.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `symbol` | string | Yes | Stock ticker symbol |\n\n**Returns:** JSON array of news items with title, summary, publication date, provider, URL, and thumbnail.\n\n### `yfinance_search`\n\nSearch Yahoo Finance for stocks, ETFs, and news articles.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `query` | string | Yes | Search query — company name, ticker symbol, or keywords |\n| `search_type` | string | Yes | `\"all\"` (quotes + news), `\"quotes\"` (stocks/ETFs only), or `\"news\"` (articles only) |\n\n**Returns:** Matching quotes and/or news results depending on `search_type`.\n\n### `yfinance_get_top`\n\nGet top-ranked financial entities within a market sector.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `sector` | string | Yes | Market sector (see [supported sectors](#supported-sectors) below) |\n| `top_type` | string | Yes | `\"top_etfs\"`, `\"top_mutual_funds\"`, `\"top_companies\"`, `\"top_growth_companies\"`, or `\"top_performing_companies\"` |\n| `top_n` | number | No | Number of results to return (default: `10`, max: `100`) |\n\n**Returns:** JSON array of top entities with relevant metrics.\n\n#### Supported Sectors\n\n`Basic Materials`, `Communication Services`, `Consumer Cyclical`, `Consumer Defensive`, `Energy`, `Financial Services`, `Healthcare`, `Industrials`, `Real Estate`, `Technology`, `Utilities`\n\n### `yfinance_screen`\n\nRun Yahoo Finance screeners using either predefined screener keys or custom query trees.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `query` | string/object | Yes | For `query_type=\"predefined\"`: screener key such as `\"day_gainers\"`. For `query_type=\"equity\"`, `\"fund\"`, or `\"etf\"`: custom query tree with `{operator, operands}` nodes |\n| `query_type` | string | No | `\"predefined\"` (default), `\"equity\"`, `\"fund\"`, or `\"etf\"` |\n| `offset` | number | No | Result offset |\n| `size` | number | No | Rows for custom queries; Yahoo maximum is `250` |\n| `count` | number | No | Rows for predefined queries; Yahoo maximum is `250` |\n| `sort_field` | string | No | Sort field, for example `\"percentchange\"` |\n| `sort_asc` | boolean | No | Sort ascending if `true`, descending if `false` |\n| `user_id` | string | No | Optional Yahoo user identifier |\n| `user_id_type` | string | No | Optional Yahoo user ID type, commonly `\"guid\"` |\n\n**Returns:** JSON screener response from Yahoo Finance, typically including quote rows and metadata.\n\nCustom equity screener example:\n\n```json\n{\n  \"query_type\": \"equity\",\n  \"query\": {\n    \"operator\": \"and\",\n    \"operands\": [\n      { \"operator\": \"gt\", \"operands\": [\"percentchange\", 3] },\n      { \"operator\": \"eq\", \"operands\": [\"region\", \"us\"] },\n      { \"operator\": \"gte\", \"operands\": [\"intradayprice\", 5] },\n      { \"operator\": \"gt\", \"operands\": [\"dayvolume\", 500000] }\n    ]\n  },\n  \"sort_field\": \"percentchange\",\n  \"sort_asc\": false,\n  \"size\": 50\n}\n```\n\nCustom ETF screener example:\n\n```json\n{\n  \"query_type\": \"etf\",\n  \"query\": {\n    \"operator\": \"and\",\n    \"operands\": [\n      { \"operator\": \"eq\", \"operands\": [\"categoryname\", \"Large Blend\"] },\n      { \"operator\": \"lte\", \"operands\": [\"annualreportnetexpenseratio\", 0.2] }\n    ]\n  },\n  \"sort_field\": \"fundnetassets\",\n  \"sort_asc\": false,\n  \"size\": 25\n}\n```\n\n### `yfinance_screen_gappers`\n\nRun a purpose-built custom screener for opening-session bullish gappers.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `min_percent_change` | number | No | Minimum percent gap/change from prior close (default: `3.0`) |\n| `min_price` | number | No | Minimum intraday price (default: `5.0`) |\n| `min_volume` | number | No | Minimum day volume (default: `500000`) |\n| `min_market_cap` | number | No | Minimum intraday market cap in USD (default: `2000000000`) |\n| `region` | string | No | Yahoo region code (default: `\"us\"`) |\n| `size` | number | No | Number of results (default: `50`, max: `250`) |\n| `offset` | number | No | Result offset for pagination (default: `0`) |\n| `sort_asc` | boolean | No | Sort by `percentchange` ascending (`true`) or descending (`false`, default) |\n\n**Returns:** JSON screener response from Yahoo Finance.\n\n### `yfinance_get_price_history`\n\nFetch historical price data and optionally generate technical analysis charts.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `symbol` | string | Yes | Stock ticker symbol |\n| `period` | string | No | Time range — `1d`, `5d`, `1mo`, `3mo`, `6mo`, `1y`, `2y`, `5y`, `10y`, `ytd`, `max` (default: `1mo`) |\n| `interval` | string | No | Data granularity — `1m`, `2m`, `5m`, `15m`, `30m`, `60m`, `90m`, `1h`, `1d`, `5d`, `1wk`, `1mo`, `3mo` (default: `1d`) |\n| `chart_type` | string | No | Chart to generate (omit for tabular data) |\n| `prepost` | boolean | No | Include pre-market and post-market data when available (default: `false`; useful with intraday requests like `period=\"1d\"`, `interval=\"1m\"`) |\n\n**Chart types:**\n\n| Value | Description |\n|-------|-------------|\n| `\"price_volume\"` | Candlestick chart with volume bars |\n| `\"vwap\"` | Price chart with Volume Weighted Average Price overlay |\n| `\"volume_profile\"` | Candlestick chart with volume distribution by price level |\n\n**Returns:**\n- Without `chart_type`: Markdown table with Date, Open, High, Low, Close, Volume, Dividends, and Stock Splits columns.\n- With `chart_type`: Base64-encoded WebP image for efficient token usage.\n\n### `yfinance_get_financials`\n\nFetch financial statements (income statement, balance sheet, and cash flow) with historical data.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `symbol` | string | Yes | Stock ticker symbol |\n| `frequency` | string | No | `\"annual\"` (yearly), `\"quarterly\"` (quarterly), or `\"ttm\"` (trailing twelve months). Default: `\"annual\"` |\n\n**Returns:** JSON object with income statement, balance sheet, and cash flow data for each reporting period.\n\n- **Income Statement fields**: EBIT, Net Income, Tax Provision, Pretax Income, Interest Expense, Total Revenue, Operating Income, EBITDA, Normalized Income\n- **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\n- **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\n\n### `yfinance_get_holders`\n\nFetch major holders, institutional holders, mutual fund holders, and insider data.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `symbol` | string | Yes | Stock ticker symbol (e.g. `AAPL`, `MSFT`) |\n| `max_rows` | number | No | Maximum rows returned per holder section. Default: `10`. Use `0` to return all rows |\n\n**Returns:** JSON object with:\n- **`major_holders`** — Aggregated breakdown where each row has an `index` label (e.g. `insidersPercentHeld`, `institutionsPercentHeld`, `institutionsFloatPercentHeld`, `institutionsCount`) and a `Value`\n- **`institutional_holders`** — Institutional investors; records typically include fields such as `Date Reported`, `Holder`, `Shares`, `Value`, `pctChange`, `pctHeld`\n- **`mutualfund_holders`** — Mutual fund holders; records typically include fields similar to institutional holders\n- **`insider_transactions`** — Recent insider trades; records typically include fields such as `Shares`, `Value`, `Insider`, `Position`, `Transaction`, `Start Date`, `Ownership`\n- **`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`\n- **`insider_roster`** — Known insiders; records typically include fields such as `Name`, `Position`, `Shares Owned Directly`, `Most Recent Transaction`, `Latest Transaction Date`\n- **`_metadata`** — Row limit metadata with `max_rows` and per-section `total_rows`, `returned_rows`, and `truncated`\n\nHolder 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.\n\n### `yfinance_get_fund_data`\n\nFetch ETF or mutual-fund portfolio composition and operating details.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `symbol` | string | Yes | ETF or mutual-fund ticker symbol (for example `SPY`, `BND`, or `VFIAX`) |\n| `sections` | array | No | Any of `description`, `fund_overview`, `fund_operations`, `asset_classes`, `top_holdings`, `equity_holdings`, `bond_holdings`, `bond_ratings`, or `sector_weightings`. Omit for all sections |\n| `max_rows` | number | No | Maximum rows per tabular section. Default: `25`. Use `0` for all rows |\n\n**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.\n\n### `yfinance_get_option_dates`\n\nFetch available option expiration dates for a stock.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `symbol` | string | Yes | Stock ticker symbol (e.g. `AAPL`, `MSFT`) |\n\n**Returns:** JSON array of expiration dates in YYYY-MM-DD format.\n\n### `yfinance_get_option_chain`\n\nFetch option chain data (calls and puts) for a stock with available strike prices.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `symbol` | string | Yes | Stock ticker symbol |\n| `expiration_date` | string | No | Option expiration date in YYYY-MM-DD format. Omit to fetch all dates. |\n| `option_type` | string | No | `\"calls\"`, `\"puts\"`, or `\"all\"` (default: `\"all\"`) |\n\n**Returns:** JSON object keyed by expiration date, with calls and/or puts data including:\n- `contractSymbol`: Option contract identifier\n- `strike`: Strike price\n- `lastPrice`: Last traded price\n- `bid`/`ask`: Bid and ask prices\n- `volume`: Trading volume\n- `openInterest`: Open interest\n- `impliedVolatility`: IV\n- `inTheMoney`: Whether option is ITM\n- `contractSize`: Contract size (REGULAR)\n- `currency`: Currency (USD)\n\n## Usage\n\n### Via uv (recommended)\n\n1. [Install uv](https://docs.astral.sh/uv/getting-started/installation/)\n2. Add the following to your MCP client configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"yfmcp\": {\n      \"command\": \"uvx\",\n      \"args\": [\"yfmcp@latest\"]\n    }\n  }\n}\n```\n\n### Via Docker\n\n```json\n{\n  \"mcpServers\": {\n    \"yfmcp\": {\n      \"command\": \"docker\",\n      \"args\": [\"run\", \"-i\", \"--rm\", \"narumi/yfinance-mcp\"]\n    }\n  }\n}\n```\n\n### From Source\n\n1. Clone the repository and install dependencies:\n\n```bash\ngit clone https://github.com/narumiruna/yfinance-mcp.git\ncd yfinance-mcp\nuv sync\n```\n\n2. Add the following to your MCP client configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"yfmcp\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"run\",\n        \"--directory\",\n        \"/path/to/yfinance-mcp\",\n        \"yfmcp\"\n      ]\n    }\n  }\n}\n```\n\nReplace `/path/to/yfinance-mcp` with the actual path to your cloned repository.\n\n### Testing with Codex CLI\n\nThis 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:\n\n```text\nShow VOO ticker info\nShow VOO price history for the last 5 days\nFind the ticker symbol for Toyota\nGet AAPL option expiration dates\n```\n\n## Development\n\n### Prerequisites\n\n- Python ≥ 3.12\n- [uv](https://docs.astral.sh/uv/) package manager\n\n### Setup\n\n```bash\nuv sync --extra dev\n```\n\n### Lint & Format\n\n```bash\nuv run ruff check .\nuv run ruff format .\n```\n\n### Type Check\n\n```bash\nuv run ty check src tests\n```\n\n### Test\n\n```bash\nuv run pytest -v -s --cov=src tests\n```\n\n## Demo Chatbot\n\nSee the demo chatbot in its dedicated repository: [yfinance-mcp-demo](https://github.com/narumiruna/yfinance-mcp-demo)\n\n## Contributors\n\n<a href=\"https://github.com/narumiruna/yfinance-mcp/graphs/contributors\">\n  <img src=\"https://contrib.rocks/image?repo=narumiruna/yfinance-mcp\" />\n</a>\n\nMade with [contrib.rocks](https://contrib.rocks).\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE).\n",
  "bytes": 17457,
  "sha": "3e0d133398ad78754666f8f8ec879d2fad779af0c2d54e5378e7aa5ef0c4927e",
  "repo_slug": "narumiruna/yfinance-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_narumiruna_yfinance_mcp_a56f2123/readme"
}