
A Model Context Protocol (MCP) server that provides AI assistants with access to Yahoo Finance data
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.
·
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.
yfinance_get_ticker_infoRetrieve comprehensive stock data including company info, financials, trading metrics, and governance data.
| Parameter | Type | Required | Description |
|---|---|---|---|
symbol | string | Yes | Stock ticker symbol (e.g. AAPL, GOOGL, MSFT) |
Returns: JSON object with company details, price data, valuation metrics, trading info, dividends, financials, and performance indicators.
yfinance_get_analyst_price_targetsFetch the current price and analyst consensus price targets for a stock.
| Parameter | Type | Required | Description |
|---|---|---|---|
symbol | string | Yes | Stock ticker symbol (e.g. AAPL, GOOGL, MSFT) |
Returns: JSON object with current, low, high, mean, and median price fields. Analyst coverage and available fields vary by symbol.
yfinance_get_analyst_estimatesFetch analyst consensus estimates, revision momentum, recommendations, growth estimates, and earnings history.
| Parameter | Type | Required | Description |
|---|---|---|---|
symbol | string | Yes | Stock ticker symbol |
sections | array | No | Any of recommendations, earnings_estimate, revenue_estimate, eps_trend, eps_revisions, earnings_history, or growth_estimates. Omit for all sections |
max_rows | number | No | Maximum rows per section. Default: 12. Use 0 for all rows |
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_downgradesFetch analyst upgrades, downgrades, initiations, reiterations, and price-target changes, newest first.
| Parameter | Type | Required | Description |
|---|---|---|---|
symbol | string | Yes | Stock ticker symbol |
max_rows | number | No | Maximum actions to return. Default: 25. Use 0 to return all rows |
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 actionFirm: Analyst firm nameToGrade and FromGrade: New and previous ratingsAction: Rating actionpriceTargetAction: Price-target action such as Raises, Lowers, or MaintainscurrentPriceTarget and priorPriceTarget: New and previous price targetsAvailable fields vary by symbol and analyst action.
yfinance_get_ticker_newsFetch recent news articles and press releases for a specific stock.
| Parameter | Type | Required | Description |
|---|---|---|---|
symbol | string | Yes | Stock ticker symbol |
symbol must be nonempty and contain only ASCII letters, digits, or ., -, ^, =, &, _.
Invalid input returns INVALID_PARAMS without echoing the input or calling Yahoo Finance.
Accepted formats include BRK.B, 2330.TW, ^GSPC, EURUSD=X, ES=F, and BTC-USD.
This format check does not verify that a ticker exists.
Returns: JSON array of news items with title, summary, publication date, provider, URL, and thumbnail.
yfinance_searchSearch Yahoo Finance for stocks, ETFs, and news articles.
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | Yes | Search query — company name, ticker symbol, or keywords |
search_type | string | Yes | "all" (quotes + news), "quotes" (stocks/ETFs only), or "news" (articles only) |
Returns: Matching quotes and/or news results depending on search_type.
yfinance_get_topGet top-ranked financial entities within a market sector.
| Parameter | Type | Required | Description |
|---|---|---|---|
sector | string | Yes | Market sector (see supported sectors below) |
top_type | string | Yes | "top_etfs", "top_mutual_funds", "top_companies", "top_growth_companies", or "top_performing_companies" |
top_n | number | No | Number of results to return (default: 10, max: 100) |
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
yfinance_screenRun Yahoo Finance screeners using either predefined screener keys or custom query trees.
| Parameter | Type | Required | Description |
|---|---|---|---|
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 |
query_type | string | No | "predefined" (default), "equity", "fund", or "etf" |
offset | number | No | Result offset |
size | number | No | Rows for custom queries; Yahoo maximum is 250 |
count | number | No | Rows for predefined queries; Yahoo maximum is 250 |
sort_field | string | No | Sort field, for example "percentchange" |
sort_asc | boolean | No | Sort ascending if true, descending if false |
user_id | string | No | Optional Yahoo user identifier |
user_id_type | string | No | Optional Yahoo user ID type, commonly "guid" |
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_gappersRun a purpose-built custom screener for opening-session bullish gappers.
| Parameter | Type | Required | Description |
|---|---|---|---|
min_percent_change | number | No | Minimum percent gap/change from prior close (default: 3.0) |
min_price | number | No | Minimum intraday price (default: 5.0) |
min_volume | number | No | Minimum day volume (default: 500000) |
min_market_cap | number | No | Minimum intraday market cap in USD (default: 2000000000) |
region | string | No | Yahoo region code (default: "us") |
size | number | No | Number of results (default: 50, max: 250) |
offset | number | No | Result offset for pagination (default: 0) |
sort_asc | boolean | No | Sort by percentchange ascending (true) or descending (false, default) |
Returns: JSON screener response from Yahoo Finance.
yfinance_get_price_historyFetch historical price data and optionally generate technical analysis charts.
| Parameter | Type | Required | Description |
|---|---|---|---|
symbol | string | Yes | Stock ticker symbol |
period | string | No | Time range — 1d, 5d, 1mo, 3mo, 6mo, 1y, 2y, 5y, 10y, ytd, max (default: 1mo) |
interval | string | No | Data granularity — 1m, 2m, 5m, 15m, 30m, 60m, 90m, 1h, 1d, 5d, 1wk, 1mo, 3mo (default: 1d) |
chart_type | string | No | Chart to generate (omit for tabular data) |
prepost | boolean | No | Include pre-market and post-market data when available (default: false; useful with intraday requests like period="1d", interval="1m") |
Chart types:
| Value | Description |
|---|---|
"price_volume" | Candlestick chart with volume bars |
"vwap" | Price chart with Volume Weighted Average Price overlay |
"volume_profile" | Candlestick chart with volume distribution by price level |
Returns:
chart_type: Markdown table with Date, Open, High, Low, Close, Volume, Dividends, and Stock Splits columns.chart_type: Base64-encoded WebP image for efficient token usage.yfinance_get_financialsFetch financial statements (income statement, balance sheet, and cash flow) with historical data.
| Parameter | Type | Required | Description |
|---|---|---|---|
symbol | string | Yes | Stock ticker symbol |
frequency | string | No | "annual" (yearly), "quarterly" (quarterly), or "ttm" (trailing twelve months). Default: "annual" |
Returns: JSON object with income statement, balance sheet, and cash flow data for each reporting period.
yfinance_get_holdersFetch major holders, institutional holders, mutual fund holders, and insider data.
| Parameter | Type | Required | Description |
|---|---|---|---|
symbol | string | Yes | Stock ticker symbol (e.g. AAPL, MSFT) |
max_rows | number | No | Maximum rows returned per holder section. Default: 10. Use 0 to return all rows |
Returns: JSON object with:
major_holders — Aggregated breakdown where each row has an index label (e.g. insidersPercentHeld, institutionsPercentHeld, institutionsFloatPercentHeld, institutionsCount) and a Valueinstitutional_holders — Institutional investors; records typically include fields such as Date Reported, Holder, Shares, Value, pctChange, pctHeldmutualfund_holders — Mutual fund holders; records typically include fields similar to institutional holdersinsider_transactions — Recent insider trades; records typically include fields such as Shares, Value, Insider, Position, Transaction, Start Date, Ownershipinsider_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, Transinsider_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 truncatedHolder 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_dataFetch ETF or mutual-fund portfolio composition and operating details.
| Parameter | Type | Required | Description |
|---|---|---|---|
symbol | string | Yes | ETF or mutual-fund ticker symbol (for example SPY, BND, or VFIAX) |
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 |
max_rows | number | No | Maximum rows per tabular section. Default: 25. Use 0 for all rows |
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_datesFetch available option expiration dates for a stock.
| Parameter | Type | Required | Description |
|---|---|---|---|
symbol | string | Yes | Stock ticker symbol (e.g. AAPL, MSFT) |
Returns: JSON array of expiration dates in YYYY-MM-DD format.
yfinance_get_option_chainFetch option chain data (calls and puts) for a stock with available strike prices.
| Parameter | Type | Required | Description |
|---|---|---|---|
symbol | string | Yes | Stock ticker symbol |
expiration_date | string | No | Option expiration date in YYYY-MM-DD format. Omit to fetch all dates. |
option_type | string | No | "calls", "puts", or "all" (default: "all") |
Returns: JSON object keyed by expiration date, with calls and/or puts data including:
contractSymbol: Option contract identifierstrike: Strike pricelastPrice: Last traded pricebid/ask: Bid and ask pricesvolume: Trading volumeopenInterest: Open interestimpliedVolatility: IVinTheMoney: Whether option is ITMcontractSize: Contract size (REGULAR)currency: Currency (USD){
"mcpServers": {
"yfmcp": {
"command": "uvx",
"args": ["yfmcp@latest"]
}
}
}{
"mcpServers": {
"yfmcp": {
"command": "docker",
"args": ["run", "-i", "--rm", "narumi/yfinance-mcp"]
}
}
}git clone https://github.com/narumiruna/yfinance-mcp.git
cd yfinance-mcp
uv sync{
"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 datesuv sync --extra devuv run ruff check .
uv run ruff format .uv run ty check src testsuv run pytest -v -s --cov=src testsSee the demo chatbot in its dedicated repository: yfinance-mcp-demo
Made with contrib.rocks.
This project is licensed under the MIT License.
Pick your client and paste the snippet. Each one is the same server, written the way that client expects it.
claude mcp add yfmcp -- uvx yfmcp@latest{
"mcpServers": {
"yfmcp": {
"args": [
"yfmcp@latest"
],
"command": "uvx"
}
}
}code --add-mcp '{"name":"yfmcp","args":["yfmcp@latest"],"command":"uvx"}'[mcp_servers.yfmcp]
command = "uvx"
args = ["yfmcp@latest"]Runs locally on your device. Your client starts the server itself, so nothing has to be hosted.
Paste this prompt into your agent. It reads this page and does the setup for you.
Read https://aiagentslisting.com/mcp/yahoo-finance-mcp-server to learn what the "Yahoo Finance MCP Server" MCP server does and how to install it. Add it to my coding agent's MCP configuration as documented on that page, then confirm the server connects and list the tools it exposes.Agents can also browse this directory over MCP at https://aiagentslisting.com/api/mcp
This server runs locally, so we can't read its tool list over the web yet.
We could not run this server: it ships no npx package for our sandbox and no public endpoint. The four checks that need a live server are left out, and the grade tops out at B until one exists.
Maintain this server? Claiming proves you own the listing and earns the last 4 points.
Claim this listingPaste this line near the top of your repository's README. The badge always renders the current score.
[](https://aiagentslisting.com/mcp/yahoo-finance-mcp-server)Nothing comparable is listed yet.
v0.14.0Release notesv0.13.0Release notesv0.12.4Release notesv0.12.3Release notesv0.12.2Release notesv0.12.1Release notesv0.12.0Release notesv0.11.3Release notesv0.11.2Release notesConnect to the AI Agents Listing MCP server at https://aiagentslisting.com/api/mcp using the HTTP transport and complete the sign-in when it asks. Then call the submit_review tool for the listing "yahoo-finance-mcp-server" with a rating from 1 to 5 and a short note on what worked and what did not.No reviews yet
Be the first to share your experience with this tool.
One email a week. New agents, MCP servers and skills, and what is actually getting traction.