Skip to content
Back to search

yfinance-mcp

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…

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/narumiruna/yfinance-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/narumiruna/yfinance-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/narumiruna--yfinance-mcp/badge.svg)](/listings/narumiruna--yfinance-mcp)

HTML

<a href="/listings/narumiruna--yfinance-mcp"><img src="/api/listings/narumiruna--yfinance-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

uv sync --extra dev

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 417 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Yahoo Finance MCP Server
  2. <!-- mcp-name: io.github.narumiruna/yfinance-mcp -->
  3. [![PyPI version](https://img.shields.io/pypi/v/yfmcp)](https://pypi.org/project/yfmcp/)
  4. [![Python](https://img.shields.io/pypi/pyversions/yfmcp.svg)](https://pypi.org/project/yfmcp/)
  5. [![CI](https://github.com/narumiruna/yfinance-mcp/actions/workflows/python.yml/badge.svg)](https://github.com/narumiruna/yfinance-mcp/actions/workflows/python.yml)
  6. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  7. A [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.
  8. ## Features
  9. - **Stock Data** — Company info, financials, valuation metrics, dividends, and trading data
  10. - **Analyst Data** — Consensus targets, estimate/revision trends, recommendation history, and firm-level actions
  11. - **Financial Statements** — Income statement and balance sheet with historical data (EBIT, Invested Capital, etc.)
  12. - **Financial News** — Recent news articles and press releases for any ticker
  13. - **Search** — Find stocks, ETFs, and news across Yahoo Finance
  14. - **Sector Rankings** — Top ETFs, mutual funds, companies, growth leaders, and top performers by sector
  15. - **Price History** — Historical OHLCV data as markdown tables or professional charts
  16. - **Chart Generation** — Candlestick, VWAP, and volume profile charts returned as WebP images
  17. - **Options Data** — Option chains with calls, puts, strike prices, IV, and expiration dates
  18. - **Ownership Data** — Major holders, institutional investors, mutual fund holders, and insider transactions
  19. - **Fund Look-Through** — ETF and mutual-fund holdings, asset classes, sectors, ratings, and operating details
  20. - **Screeners** — Predefined, equity, mutual-fund, and ETF query trees
  21. ## Tools
  22. ### `yfinance_get_ticker_info`
  23. Retrieve comprehensive stock data including company info, financials, trading metrics, and governance data.
  24. | Parameter | Type | Required | Description |
  25. |-----------|------|----------|-------------|
  26. | `symbol` | string | Yes | Stock ticker symbol (e.g. `AAPL`, `GOOGL`, `MSFT`) |
  27. **Returns:** JSON object with company details, price data, valuation metrics, trading info, dividends, financials, and performance indicators.
  28. ### `yfinance_get_analyst_price_targets`
  29. Fetch the current price and analyst consensus price targets for a stock.
  30. | Parameter | Type | Required | Description |
  31. |-----------|------|----------|-------------|
  32. | `symbol` | string | Yes | Stock ticker symbol (e.g. `AAPL`, `GOOGL`, `MSFT`) |
  33. **Returns:** JSON object with `current`, `low`, `high`, `mean`, and `median` price fields. Analyst coverage and available fields vary by symbol.
  34. ### `yfinance_get_analyst_estimates`
  35. Fetch analyst consensus estimates, revision momentum, recommendations, growth estimates, and earnings history.
  36. | Parameter | Type | Required | Description |
  37. |-----------|------|----------|-------------|
  38. | `symbol` | string | Yes | Stock ticker symbol |
  39. | `sections` | array | No | Any of `recommendations`, `earnings_estimate`, `revenue_estimate`, `eps_trend`, `eps_revisions`, `earnings_history`, or `growth_estimates`. Omit for all sections |
  40. | `max_rows` | number | No | Maximum rows per section. Default: `12`. Use `0` for all rows |
  41. **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.
  42. ### `yfinance_get_upgrades_downgrades`
  43. Fetch analyst upgrades, downgrades, initiations, reiterations, and price-target changes, newest first.
  44. | Parameter | Type | Required | Description |
  45. |-----------|------|----------|-------------|
  46. | `symbol` | string | Yes | Stock ticker symbol |
  47. | `max_rows` | number | No | Maximum actions to return. Default: `25`. Use `0` to return all rows |
  48. **Returns:** JSON object containing `upgrades_downgrades` records and `_metadata` with row counts and truncation status. Records can include:
  49. - `GradeDate`: Date and time of the analyst action
  50. - `Firm`: Analyst firm name
  51. - `ToGrade` and `FromGrade`: New and previous ratings
  52. - `Action`: Rating action
  53. - `priceTargetAction`: Price-target action such as `Raises`, `Lowers`, or `Maintains`
  54. - `currentPriceTarget` and `priorPriceTarget`: New and previous price targets
  55. Available fields vary by symbol and analyst action.
  56. ### `yfinance_get_ticker_news`
  57. Fetch recent news articles and press releases for a specific stock.
  58. | Parameter | Type | Required | Description |
  59. |-----------|------|----------|-------------|
  60. | `symbol` | string | Yes | Stock ticker symbol |
  61. `symbol` must be nonempty and contain only ASCII letters, digits, or `.`, `-`, `^`, `=`, `&`, `_`.
  62. Invalid input returns `INVALID_PARAMS` without echoing the input or calling Yahoo Finance.
  63. Accepted formats include `BRK.B`, `2330.TW`, `^GSPC`, `EURUSD=X`, `ES=F`, and `BTC-USD`.
  64. This format check does not verify that a ticker exists.
  65. **Returns:** JSON array of news items with title, summary, publication date, provider, URL, and thumbnail.
  66. ### `yfinance_search`
  67. Search Yahoo Finance for stocks, ETFs, and news articles.
  68. | Parameter | Type | Required | Description |
  69. |-----------|------|----------|-------------|
  70. | `query` | string | Yes | Search query — company name, ticker symbol, or keywords |
  71. | `search_type` | string | Yes | `"all"` (quotes + news), `"quotes"` (stocks/ETFs only), or `"news"` (articles only) |
  72. **Returns:** Matching quotes and/or news results depending on `search_type`.
  73. ### `yfinance_get_top`
  74. Get top-ranked financial entities within a market sector.
  75. | Parameter | Type | Required | Description |
  76. |-----------|------|----------|-------------|
  77. | `sector` | string | Yes | Market sector (see [supported sectors](#supported-sectors) below) |
  78. | `top_type` | string | Yes | `"top_etfs"`, `"top_mutual_funds"`, `"top_companies"`, `"top_growth_companies"`, or `"top_performing_companies"` |
  79. | `top_n` | number | No | Number of results to return (default: `10`, max: `100`) |
  80. **Returns:** JSON array of top entities with relevant metrics.
  81. #### Supported Sectors
  82. `Basic Materials`, `Communication Services`, `Consumer Cyclical`, `Consumer Defensive`, `Energy`, `Financial Services`, `Healthcare`, `Industrials`, `Real Estate`, `Technology`, `Utilities`
  83. ### `yfinance_screen`
  84. Run Yahoo Finance screeners using either predefined screener keys or custom query trees.
  85. | Parameter | Type | Required | Description |
  86. |-----------|------|----------|-------------|
  87. | `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 |
  88. | `query_type` | string | No | `"predefined"` (default), `"equity"`, `"fund"`, or `"etf"` |
  89. | `offset` | number | No | Result offset |
  90. | `size` | number | No | Rows for custom queries; Yahoo maximum is `250` |
  91. | `count` | number | No | Rows for predefined queries; Yahoo maximum is `250` |
  92. | `sort_field` | string | No | Sort field, for example `"percentchange"` |
  93. | `sort_asc` | boolean | No | Sort ascending if `true`, descending if `false` |
  94. | `user_id` | string | No | Optional Yahoo user identifier |
  95. | `user_id_type` | string | No | Optional Yahoo user ID type, commonly `"guid"` |
  96. **Returns:** JSON screener response from Yahoo Finance, typically including quote rows and metadata.
  97. Custom equity screener example:
  98. ```json
  99. {
  100. "query_type": "equity",
  101. "query": {
  102. "operator": "and",
  103. "operands": [
  104. { "operator": "gt", "operands": ["percentchange", 3] },
  105. { "operator": "eq", "operands": ["region", "us"] },
  106. { "operator": "gte", "operands": ["intradayprice", 5] },
  107. { "operator": "gt", "operands": ["dayvolume", 500000] }
  108. ]
  109. },
  110. "sort_field": "percentchange",
  111. "sort_asc": false,
  112. "size": 50
  113. }
  114. ```
  115. Custom ETF screener example:
  116. ```json
  117. {
  118. "query_type": "etf",
  119. "query": {
  120. "operator": "and",
  121. "operands": [
  122. { "operator": "eq", "operands": ["categoryname", "Large Blend"] },
  123. { "operator": "lte", "operands": ["annualreportnetexpenseratio", 0.2] }
  124. ]
  125. },
  126. "sort_field": "fundnetassets",
  127. "sort_asc": false,
  128. "size": 25
  129. }
  130. ```
  131. ### `yfinance_screen_gappers`
  132. Run a purpose-built custom screener for opening-session bullish gappers.
  133. | Parameter | Type | Required | Description |
  134. |-----------|------|----------|-------------|
  135. | `min_percent_change` | number | No | Minimum percent gap/change from prior close (default: `3.0`) |
  136. | `min_price` | number | No | Minimum intraday price (default: `5.0`) |
  137. | `min_volume` | number | No | Minimum day volume (default: `500000`) |
  138. | `min_market_cap` | number | No | Minimum intraday market cap in USD (default: `2000000000`) |
  139. | `region` | string | No | Yahoo region code (default: `"us"`) |
  140. | `size` | number | No | Number of results (default: `50`, max: `250`) |
  141. | `offset` | number | No | Result offset for pagination (default: `0`) |
  142. | `sort_asc` | boolean | No | Sort by `percentchange` ascending (`true`) or descending (`false`, default) |
  143. **Returns:** JSON screener response from Yahoo Finance.
  144. ### `yfinance_get_price_history`
  145. Fetch historical price data and optionally generate technical analysis charts.
  146. | Parameter | Type | Required | Description |
  147. |-----------|------|----------|-------------|
  148. | `symbol` | string | Yes | Stock ticker symbol |
  149. | `period` | string | No | Time range — `1d`, `5d`, `1mo`, `3mo`, `6mo`, `1y`, `2y`, `5y`, `10y`, `ytd`, `max` (default: `1mo`) |
  150. | `interval` | string | No | Data granularity — `1m`, `2m`, `5m`, `15m`, `30m`, `60m`, `90m`, `1h`, `1d`, `5d`, `1wk`, `1mo`, `3mo` (default: `1d`) |
  151. | `chart_type` | string | No | Chart to generate (omit for tabular data) |
  152. | `prepost` | boolean | No | Include pre-market and post-market data when available (default: `false`; useful with intraday requests like `period="1d"`, `interval="1m"`) |
  153. **Chart types:**
  154. | Value | Description |
  155. |-------|-------------|
  156. | `"price_volume"` | Candlestick chart with volume bars |
  157. | `"vwap"` | Price chart with Volume Weighted Average Price overlay |
  158. | `"volume_profile"` | Candlestick chart with volume distribution by price level |
  159. **Returns:**
  160. - Without `chart_type`: Markdown table with Date, Open, High, Low, Close, Volume, Dividends, and Stock Splits columns.
  161. - With `chart_type`: Base64-encoded WebP image for efficient token usage.
  162. ### `yfinance_get_financials`
  163. Fetch financial statements (income statement, balance sheet, and cash flow) with historical data.
  164. | Parameter | Type | Required | Description |
  165. |-----------|------|----------|-------------|
  166. | `symbol` | string | Yes | Stock ticker symbol |
  167. | `frequency` | string | No | `"annual"` (yearly), `"quarterly"` (quarterly), or `"ttm"` (trailing twelve months). Default: `"annual"` |
  168. **Returns:** JSON object with income statement, balance sheet, and cash flow data for each reporting period.
  169. - **Income Statement fields**: EBIT, Net Income, Tax Provision, Pretax Income, Interest Expense, Total Revenue, Operating Income, EBITDA, Normalized Income
  170. - **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
  171. - **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
  172. ### `yfinance_get_holders`
  173. Fetch major holders, institutional holders, mutual fund holders, and insider data.
  174. | Parameter | Type | Required | Description |
  175. |-----------|------|----------|-------------|
  176. | `symbol` | string | Yes | Stock ticker symbol (e.g. `AAPL`, `MSFT`) |
  177. | `max_rows` | number | No | Maximum rows returned per holder section. Default: `10`. Use `0` to return all rows |
  178. **Returns:** JSON object with:
  179. - **`major_holders`** — Aggregated breakdown where each row has an `index` label (e.g. `insidersPercentHeld`, `institutionsPercentHeld`, `institutionsFloatPercentHeld`, `institutionsCount`) and a `Value`
  180. - **`institutional_holders`** — Institutional investors; records typically include fields such as `Date Reported`, `Holder`, `Shares`, `Value`, `pctChange`, `pctHeld`
  181. - **`mutualfund_holders`** — Mutual fund holders; records typically include fields similar to institutional holders
  182. - **`insider_transactions`** — Recent insider trades; records typically include fields such as `Shares`, `Value`, `Insider`, `Position`, `Transaction`, `Start Date`, `Ownership`
  183. - **`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`
  184. - **`insider_roster`** — Known insiders; records typically include fields such as `Name`, `Position`, `Shares Owned Directly`, `Most Recent Transaction`, `Latest Transaction Date`
  185. - **`_metadata`** — Row limit metadata with `max_rows` and per-section `total_rows`, `returned_rows`, and `truncated`
  186. 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.
  187. ### `yfinance_get_fund_data`
  188. Fetch ETF or mutual-fund portfolio composition and operating details.
  189. | Parameter | Type | Required | Description |
  190. |-----------|------|----------|-------------|
  191. | `symbol` | string | Yes | ETF or mutual-fund ticker symbol (for example `SPY`, `BND`, or `VFIAX`) |
  192. | `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 |
  193. | `max_rows` | number | No | Maximum rows per tabular section. Default: `25`. Use `0` for all rows |
  194. **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.
  195. ### `yfinance_get_option_dates`
  196. Fetch available option expiration dates for a stock.
  197. | Parameter | Type | Required | Description |
  198. |-----------|------|----------|-------------|
  199. | `symbol` | string | Yes | Stock ticker symbol (e.g. `AAPL`, `MSFT`) |
  200. **Returns:** JSON array of expiration dates in YYYY-MM-DD format.
  201. ### `yfinance_get_option_chain`
  202. Fetch option chain data (calls and puts) for a stock with available strike prices.
  203. | Parameter | Type | Required | Description |
  204. |-----------|------|----------|-------------|
  205. | `symbol` | string | Yes | Stock ticker symbol |
  206. | `expiration_date` | string | No | Option expiration date in YYYY-MM-DD format. Omit to fetch all dates. |
  207. | `option_type` | string | No | `"calls"`, `"puts"`, or `"all"` (default: `"all"`) |
  208. **Returns:** JSON object keyed by expiration date, with calls and/or puts data including:
  209. - `contractSymbol`: Option contract identifier
  210. - `strike`: Strike price
  211. - `lastPrice`: Last traded price
  212. - `bid`/`ask`: Bid and ask prices
  213. - `volume`: Trading volume
  214. - `openInterest`: Open interest
  215. - `impliedVolatility`: IV
  216. - `inTheMoney`: Whether option is ITM
  217. - `contractSize`: Contract size (REGULAR)
  218. - `currency`: Currency (USD)
  219. ## Usage
  220. ### Via uv (recommended)
  221. 1. [Install uv](https://docs.astral.sh/uv/getting-started/installation/)
  222. 2. Add the following to your MCP client configuration:
  223. ```json
  224. {
  225. "mcpServers": {
  226. "yfmcp": {
  227. "command": "uvx",
  228. "args": ["yfmcp@latest"]
  229. }
  230. }
  231. }
  232. ```
  233. ### Via Docker
  234. ```json
  235. {
  236. "mcpServers": {
  237. "yfmcp": {
  238. "command": "docker",
  239. "args": ["run", "-i", "--rm", "narumi/yfinance-mcp"]
  240. }
  241. }
  242. }
  243. ```
  244. ### From Source
  245. 1. Clone the repository and install dependencies:
  246. ```bash
  247. git clone https://github.com/narumiruna/yfinance-mcp.git
  248. cd yfinance-mcp
  249. uv sync
  250. ```
  251. 2. Add the following to your MCP client configuration:
  252. ```json
  253. {
  254. "mcpServers": {
  255. "yfmcp": {
  256. "command": "uv",
  257. "args": [
  258. "run",
  259. "--directory",
  260. "/path/to/yfinance-mcp",
  261. "yfmcp"
  262. ]
  263. }
  264. }
  265. }
  266. ```
  267. Replace `/path/to/yfinance-mcp` with the actual path to your cloned repository.
  268. ### Testing with Codex CLI
  269. 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:
  270. ```text
  271. Show VOO ticker info
  272. Show VOO price history for the last 5 days
  273. Find the ticker symbol for Toyota
  274. Get AAPL option expiration dates
  275. ```
  276. ## Development
  277. ### Prerequisites
  278. - Python ≥ 3.12
  279. - [uv](https://docs.astral.sh/uv/) package manager
  280. ### Setup
  281. ```bash
  282. uv sync --extra dev
  283. ```
  284. ### Lint & Format
  285. ```bash
  286. uv run ruff check .
  287. uv run ruff format .
  288. ```
  289. ### Type Check
  290. ```bash
  291. uv run ty check src tests
  292. ```
  293. ### Test
  294. ```bash
  295. uv run pytest -v -s --cov=src tests
  296. ```
  297. ## Demo Chatbot
  298. See the demo chatbot in its dedicated repository: [yfinance-mcp-demo](https://github.com/narumiruna/yfinance-mcp-demo)
  299. ## Contributors
  300. <a href="https://github.com/narumiruna/yfinance-mcp/graphs/contributors">
  301. <img src="https://contrib.rocks/image?repo=narumiruna/yfinance-mcp" />
  302. </a>
  303. Made with [contrib.rocks](https://contrib.rocks).
  304. ## License
  305. This project is licensed under the [MIT License](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.