How do I use yahoo-finance-mcp-server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@yahoo-finance-mcp-server Show me the current stock price for AAPL." That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

yahoo-finance-mcp-server

by christianGRogers

Overview Schema Source Related Servers Discussions Admin

Python

Remote

Yahoo Finance MCP Server

I built this at purpose invest because fuck bloomberg but realized having claude call the yahoo python library was more efficient so this is kinda pointless

An MCP server that exposes the full Yahoo Finance data surface to AI agents, backed by the yfinance library. No API key required.

Note on the "Yahoo Finance API": Yahoo retired its official public finance API years ago. This server uses yfinance, which wraps Yahoo's internal query1/query2.finance.yahoo.com endpoints (handling cookie/crumb auth for you). It is the most complete free way to access Yahoo's data, but it is unofficial — endpoints can change or rate-limit without notice.

Live deployment

A hosted instance is deployed and running at:

https://janus.bradensbay.com/mcp

It speaks MCP over streamable HTTP. Add it to Claude Code with one command — no local install required:

claude mcp add --transport http --scope project yahoo-finance https://janus.bradensbay.com/mcp

--scope project writes the server to this project's .mcp.json so it's shared with anyone who checks out the repo. Drop the flag for a personal (per-user) entry, or use --scope user to make it available across all your projects.

Verify the connection:

claude mcp list            # lists configured servers + reachability
claude mcp get yahoo-finance

Quick health check of the endpoint itself (expects HTTP 200):

curl -i -X POST https://janus.bradensbay.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'

Prefer running your own instance (locally over stdio, or self-hosted over HTTP)? See Installation and Deployment below.

Related MCP server: openmarkets

What the agent can see

Every major data category Yahoo Finance serves is exposed as a tool:

Tool	Data
`get_quote`	Fast price snapshot (last/open/high/low, volume, market cap, 52-wk range)
`get_ticker_info`	Full company/security profile (`.info`): sector, ratios, margins, targets, summary
`get_isin`	ISIN identifier
`get_historical_prices`	OHLCV history by period or date range, any interval (1m → 3mo)
`download_multiple`	Batch historical prices for many symbols at once
`get_corporate_actions`	Dividends, splits, capital gains
`get_financial_statements`	Income statement / balance sheet / cash flow (annual & quarterly)
`get_earnings`	Earnings calendar & dates, EPS/revenue estimates, EPS trend & growth
`get_analyst_data`	Recommendations, price targets, upgrades/downgrades
`get_holders`	Major / institutional / mutual-fund holders + insider activity
`get_shares`	Historical shares outstanding
`get_sustainability`	ESG risk scores
`get_option_expirations`	Available option expiry dates
`get_option_chain`	Calls & puts (strike, IV, OI, volume, bid/ask) for an expiry
`get_news`	Recent related news articles
`get_sec_filings`	Recent SEC filings with document links
`get_fund_data`	ETF/mutual-fund holdings, allocations, sector weights, bond ratings
`search`	Resolve a name → symbol; matching quotes + news
`lookup`	Enumerate instruments by type (stock/etf/index/currency/crypto/…)
`get_sector`	Sector overview, top companies/ETFs, industries
`get_industry`	Industry overview, top performing/growth companies
`get_market_status`	Market open/closed status & index summary by region
`screen_predefined`	Preset screens (day_gainers, most_actives, …)
`screen_custom`	Custom numeric screen (e.g. market cap > $1B)

Tickers use Yahoo symbols: AAPL, MSFT, BTC-USD, ^GSPC, EURUSD=X.

Installation

Requires Python 3.10+.

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Running

The server speaks MCP over stdio:

yahoo-finance-mcp
# or
python -m yahoo_finance_mcp

Claude Desktop / Claude Code config

Add to your MCP client config (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "yahoo-finance": {
      "command": "/absolute/path/to/yahoo-finance-mcp-server/.venv/bin/python",
      "args": ["-m", "yahoo_finance_mcp"]
    }
  }
}

Or, with Claude Code:

claude mcp add yahoo-finance -- /absolute/path/to/.venv/bin/python -m yahoo_finance_mcp

Deployment (HTTP, port 8081)

For remote/agent access the server can run over streamable HTTP instead of stdio. Transport and binding are controlled by env vars:

Var	Default	Purpose
`MCP_TRANSPORT`	`stdio`	`streamable-http` (or `sse`) to serve over HTTP
`MCP_HOST`	`0.0.0.0`	bind address
`MCP_PORT`	`8081`	listen port

Run it directly:

MCP_TRANSPORT=streamable-http MCP_PORT=8081 python -m yahoo_finance_mcp
# endpoint: http://<host>:8081/mcp

Automated deploy via SSH

deploy/deploy.sh ships the code to a remote host, installs it, and (re)starts it on port 8081 with a health check. It authenticates over SSH using these GitHub repository secrets:

Secret	Meaning
`DEPLOY_SSH_HOST`	remote endpoint (host/IP)
`DEPLOY_SSH_PORT`	SSH port
`DEPLOY_SSH_USER`	SSH username
`DEPLOY_SSH_PASSWORD`	SSH password

Python is auto-provisioned. The script needs Python ≥ 3.10. It first scans the remote for any installed interpreter that qualifies (python3.10–3.13, including /usr/local/bin). If none is found — e.g. on Raspberry Pi OS Bullseye, which ships only Python 3.9.2 — it installs build deps and compiles CPython (default 3.11.9, override with PYTHON_BUILD_VERSION) to /usr/local via make altinstall. This one-time bootstrap takes ~15–40 min on a Pi; subsequent deploys detect the installed interpreter and skip it.

Building requires root: it works if the deploy user has passwordless sudo, otherwise it falls back to sudo -S using DEPLOY_SSH_PASSWORD. You can still set PYTHON_BIN to force a specific interpreter; it's used if it qualifies.

The .github/workflows/deploy.yml workflow runs the script on every push to main (and on manual workflow_dispatch). To run it by hand:

DEPLOY_SSH_HOST=1.2.3.4 DEPLOY_SSH_PORT=22 \
DEPLOY_SSH_USER=pi DEPLOY_SSH_PASSWORD=secret \
PYTHON_BIN=python3.11 \
./deploy/deploy.sh

The script clones/updates the repo, builds a venv, stops any prior instance on the port, starts the server detached (setsid, survives disconnect, logs to server.log), then verifies POST /mcp returns 200.

Notes & limitations

Unofficial data source. Yahoo may rate-limit or change responses. Tools return a structured {"error": ...} payload instead of crashing when a call fails, so the agent can react.
Intraday history is range-limited by Yahoo (e.g. 1m data only for the last few days).
Data is provided for informational purposes; respect Yahoo's Terms of Service. Not investment advice.

Development

pip install -e .
python -c "from yahoo_finance_mcp.server import mcp; print(len(mcp._tool_manager.list_tools()), 'tools')"

Available Tools

24 tools

download_multipleA

Download historical prices for MULTIPLE symbols at once.

Efficient batch alternative to calling get_historical_prices repeatedly. Returns a per-symbol dict of date-indexed OHLCV data.

Inputs: symbols (required), end, start, period, +2 more.

get_analyst_dataB

Get analyst recommendations, price targets and upgrade/downgrade history.

Returns recommendations and recommendations_summary (buy/hold/sell counts over recent months), analyst_price_targets (current/high/low/mean target), and upgrades_downgrades (firm-by-firm rating changes).

Inputs: symbol (required).

get_corporate_actionsB

Get dividends, stock splits and capital gains history for a symbol.

Returns three date-keyed series: dividends (per-share amounts), splits (split ratios) and capital_gains (mainly for funds).

Inputs: symbol (required).

get_earningsB

Get earnings calendar, upcoming/historical earnings dates and estimates.

Returns the calendar (next earnings & dividend dates), earnings_dates (reported vs estimated EPS per period with surprise %), and the various forward estimate tables (EPS estimate, revenue estimate, EPS trend & growth).

Inputs: symbol (required).

get_financial_statementsA

Get financial statements (income statement, balance sheet, cash flow).

statement selects one statement or "all" (default). freq toggles annual vs quarterly. Values are keyed by line item, with periods as columns. Data goes back several years/quarters depending on Yahoo coverage.

Inputs: symbol (required), freq, statement.

get_fund_dataA

Get ETF / mutual fund specifics: description, holdings, sector & asset allocation, top holdings, bond ratings and fund operations.

Only meaningful for funds/ETFs (e.g. SPY, VTI, QQQ). For ordinary stocks this returns little or an error.

Inputs: symbol (required).

get_historical_pricesA

Get historical OHLCV price data for a symbol.

Provide either period (e.g. "1y") OR an explicit start/end date range ("YYYY-MM-DD"); if start/end are given they take precedence over period. interval controls granularity — intraday intervals (1m..1h) are only available for recent ranges (Yahoo limits ~7-60 days). Returns a dict keyed by ISO timestamp with Open/High/Low/Close/Volume (and Dividends/Splits when actions is true). history_metadata includes timezone & instrument info.

Inputs: symbol (required), end, start, period, +4 more.

get_holdersA

Get ownership breakdown: major, institutional, mutual fund and insiders.

Returns major_holders (% insider/institutional), institutional_holders and mutualfund_holders (top holders with shares & value), plus insider data: insider_purchases, insider_transactions, insider_roster_holders.

Inputs: symbol (required).

get_industryA

Get industry overview data by industry key (e.g. "semiconductors", "software-infrastructure", "biotechnology", "banks-diversified").

Returns the industry overview, top performing/growth companies and top ETFs.

Inputs: key (required).

get_isinC

Get the ISIN (International Securities Identification Number) for a symbol.

Inputs: symbol (required).

get_market_statusA

Get market status and summary for a region (e.g. "US", "GB", "ASIA", "EUROPE"). Returns whether the market is open and a summary of major indices.

Inputs: market.

get_newsC

Get recent news articles related to a symbol (title, publisher, link, time).

Inputs: symbol (required), count.

get_option_chainA

Get the option chain (calls and puts) for a symbol and expiration date.

expiration is a "YYYY-MM-DD" date from get_option_expirations; if omitted the nearest expiry is used. Each contract includes strike, bid/ask, last price, volume, open interest, implied volatility and in-the-money flag.

Inputs: symbol (required), expiration.

get_option_expirationsA

List the available option expiration dates for a symbol.

Pass one of these dates to get_option_chain to get the calls/puts table.

Inputs: symbol (required).

get_quoteA

Get a fast, lightweight current-price snapshot for a symbol.

Returns last price, previous close, open, day high/low, volume, market cap, shares, currency, exchange and 52-week range via yfinance fast_info. Use this for quick price checks; use get_ticker_info for the full profile.

Inputs: symbol (required).

get_sec_filingsC

Get recent SEC filings (10-K, 10-Q, 8-K, etc.) with dates and document links.

Inputs: symbol (required).

get_sectorA

Get sector overview data by sector key (e.g. "technology", "healthcare", "financial-services", "energy", "consumer-cyclical").

Returns the sector's overview, top companies, top ETFs/mutual funds, research reports and industry breakdown.

Inputs: key (required).

get_sharesC

Get historical shares outstanding over time (optionally a date range).

Inputs: symbol (required), end, start.

get_sustainabilityC

Get ESG / sustainability scores (environment, social, governance risk).

Inputs: symbol (required).

get_ticker_infoA

Get the full company/security profile dictionary for a symbol.

This is yfinance .info: a large dict with business summary, sector, industry, valuation ratios (PE, PEG, price-to-book), margins, dividend yield, beta, analyst target prices, address, employee count, and dozens of other fields. Best single source for fundamentals + descriptive data.

Inputs: symbol (required).

lookupA

Look up instruments matching a query, optionally filtered by asset type.

More precise than search for enumerating instruments of a given type (e.g. all ETFs matching "gold"). Returns matching symbols with metadata.

Inputs: query (required), count, lookup_type.

screen_customA

Run a custom equity screen with a single numeric criterion + region.

Example: field="intradaymarketcap", operator="gt", values=[1e9] finds companies with market cap over $1B. Common fields: intradaymarketcap, intradayprice, dayvolume, trailingpe, pegratio, epsgrowth, dividendyield, percentchange. operator "btwn" expects two values [low, high]. Results are filtered to region (e.g. "us"). Sorted by sort_field if given.

Inputs: field (required), values (required), operator (required), count, +3 more.

screen_predefinedA

Run a predefined Yahoo Finance stock/fund screen.

Handy preset screens like "day_gainers", "most_actives", "day_losers", "undervalued_growth_stocks", etc. Returns the matching quotes with key fields. For custom criteria use screen_custom.

Inputs: count, query.

searchA

Search Yahoo Finance for symbols and related news by free-text query.

Use this to resolve a company name (e.g. "Apple") to a ticker symbol, or to find related instruments and news. Returns matching quotes (symbol, name, exchange, type) and recent news.

Inputs: query (required), news_count, max_results.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.6/5.0

Scored 2026-07-05 13:45 across 24 tools

Disambiguation4/5

Most tools target distinct data types (historical prices, quotes, earnings, etc.), but get_quote and get_ticker_info both provide price information, and lookup/search both find instruments, though descriptions clarify their specific uses.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern using snake_case (e.g., get_historical_prices, search, screen_predefined), making usage predictable.

Tool Count5/5

24 tools cover a broad range of Yahoo Finance data without being excessive; each tool serves a specific purpose and the count is well-suited to the domain.

Completeness4/5

The set covers most major finance data categories (prices, fundamentals, options, holders, filings, news), but lacks some common features like technical analysis or portfolio tracking, which are minor gaps.

Resources

Related MCP Connectors

Intrinio
com.intrinio
Official Intrinio MCP server. US stock prices, options and fundamentals for AI agents.
Finance Data Platforms
1
https://intrinio-mcp.intrinio.com/mcp
Financial Modeling Prep MCP ServerA
io.github.imbenrabi
MCP server for Financial Modeling Prep API with 250+ financial data tools
Finance Open Data
51149
https://financial-modeling-prep-mcp-server-production.up.railway.app/mcp
GloomB
sh.gloom.api
Financial data MCP server for Claude, ChatGPT, Cursor and Codex. Real-time stock quotes, financial statements, options flow, SEC filings, insider trades, 13F holdings, macro data and market news from gloom.sh, the open-source Bloomberg Terminal alternative.
Finance Research & Data
711
https://api.gloom.sh/mcp
Fensory
com.fensory
Trading MCP server for AI agents, with live market data, account reads and controlled execution.
Finance Cryptocurrency Blockchain
1
https://mcp.fensory.com/mcp

Related MCP Servers

Yahoo Finance MCP Server
Finance Search
narumiruna
A
license
A
quality
B
maintenance
A simple MCP server for Yahoo Finance using yfinance. This server provides a set of tools to fetch stock data, news, and other financial information.
Updated 11 days ago (2026-11-01 14:14 UTC)
2
15
208
MIT
openmarkets
Finance Cryptocurrency
danchev
A
license
B
quality
B
maintenance
A Model Context Protocol (MCP) server for agentic retrieval of financial data from Yahoo Finance, enabling stock information, historical data, analyst data, and more.
Updated 3 days ago (2026-11-09 18:50 UTC)
71
125 PyPI
6
AGPL 3.0
Unofficial Yahoo Finance MCP
Finance Research & Data Search
benethos-hub
A
license
A
quality
B
maintenance
MCP server that exposes Yahoo Finance data through tools for searching instruments, fetching quotes, history, company info, financials, dividends, news, recommendations, and options. Enables AI assistants to answer market-data questions using natural language.
Updated a day ago (2026-11-11 15:31 UTC)
24
2,315 PyPI
2
MIT
yfinance-mcp
Finance Research & Data
monaron
F
license
Not graded
quality
C
maintenance
MCP server wrapping yfinance to provide stock market data, financials, and analytics via 24 tools.
Updated 4 months ago (2026-06-29 07:49 UTC)
-

Yahoo Finance MCP Server

Live deployment

What the agent can see

Installation

Running

Claude Desktop / Claude Code config

Deployment (HTTP, port 8081)

Automated deploy via SSH

Notes & limitations

Development

Available Tools

Tool Schema Changelog

TDQS

Resources

Related MCP Connectors

Related MCP Servers

Yahoo Finance MCP Server

openmarkets

Unofficial Yahoo Finance MCP

yfinance-mcp