Yahoo Finance MCP Server ๐

Free Yahoo Finance MCP server with no API key. 18 read-only tools give Claude, Claude Code, Cursor, VS Code, Windsurf, Codex, n8n or any other MCP client live stock quotes, historical prices, financial statements, earnings dates and calendars, analyst ratings and estimates, options chains, insider and institutional holders, stock screeners, ETF and fund holdings, sector overviews and market news. Runs locally with one npx command, over stdio or Streamable HTTP.
npm package: yahoo-finance-mcp-server ยท GitHub repo: danishashko/yahoo-finance-mcp. The repo name is shorter than the package name; both refer to this project.
๐ฏ What You Get
- ๐ Real-time stock quotes with full market data
- ๐ Historical prices (OHLCV) with summary statistics
- ๐ข Company profiles, officers, and key statistics
- ๐ฐ Financial statements (income, balance sheet, cash flow)
- ๐ฏ Analyst ratings, price targets, and the recent recommendation trend
- โ๏ธ Multi-stock comparisons side by side
- ๐ฐ Latest financial news per ticker
- ๐งพ Options chains (calls/puts, strikes, IV, open interest)
- ๐ฆ Ownership data โ institutional, mutual fund, and insider activity
- ๐ต Dividend & split history
- ๐ฎ Forward analyst estimates (price targets, EPS/revenue, growth)
- ๐ Symbol search by company name or keyword
- ๐ Market status (open/closed) and index summary
- ๐
Earnings dates: next report, beat/miss history, and a market-wide earnings calendar
- ๐งฒ Stock screeners: day gainers/losers, most active, most shorted, undervalued growth, top ETFs
- ๐งบ ETF and fund data: holdings, expense ratio, sector weights
- ๐ญ Sector and industry overviews with their largest, fastest-growing and best-performing companies
Every tool returns human-readable markdown by default, or structured JSON on request (response_format: "json"). Requests share a single browser-impersonating HTTP session to reduce Yahoo Finance rate-limiting.
๐ Quick Start
Add this to your Claude Desktop config and restart Claude:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"yahoo-finance": {
"command": "npx",
"args": ["-y", "yahoo-finance-mcp-server"]
}
}
}
That is it. On first launch the npx wrapper creates an isolated Python environment and installs the dependencies for you (a one-time step that can take a minute). You only need Python 3.10+ and Node.js 16+ on your machine.
Other clients
Claude Code
claude mcp add yahoo-finance -- npx -y yahoo-finance-mcp-server
Cursor (~/.cursor/mcp.json), Windsurf (~/.codeium/windsurf/mcp_config.json) and Gemini CLI (~/.gemini/settings.json) take the same mcpServers block as Claude Desktop above.
VS Code (.vscode/mcp.json)
{
"servers": {
"yahoo-finance": {
"type": "stdio",
"command": "npx",
"args": ["-y", "yahoo-finance-mcp-server"]
}
}
}
Codex CLI (~/.codex/config.toml)
[mcp_servers.yahoo-finance]
command = "npx"
args = ["-y", "yahoo-finance-mcp-server"]
n8n and other URL-only clients: see HTTP mode.
Prefer a global install?
npm install -g yahoo-finance-mcp-server
{
"mcpServers": {
"yahoo-finance": {
"command": "yahoo-finance-mcp-server"
}
}
}
๐ HTTP mode (n8n, remote agents, anything that connects to a URL)
Some clients spawn an MCP server as a child process and talk to it over stdio;
others only take a URL. n8n's MCP Client Tool node is the second kind - it
offers HTTP Streamable and SSE and no way to launch a command - so stdio alone
puts the server out of reach.
--http serves the same 18 tools over Streamable HTTP at /mcp:
npx -y yahoo-finance-mcp-server --http
| Flag | Default | What it does |
|---|
--http | off | Serve Streamable HTTP at /mcp instead of stdio |
--host | 127.0.0.1 | Interface to bind |
--port | 8000 | Port to bind |
--allowed-host | see below | Host header to accept, repeatable |
--stateful | off | Keep a session per client instead of stateless |
No authentication is added, so keep it on an interface you trust.
Reaching it from a container
n8n in Docker is not on your loopback interface, so bind wider and use the
host alias:
npx -y yahoo-finance-mcp-server --http --host 0.0.0.0 --port 8931
Then point the MCP Client Tool node at http://host.docker.internal:8931/mcp
with authentication set to None.
DNS-rebinding protection stays on when you bind wider. localhost,
127.0.0.1 and host.docker.internal on the bound port are accepted by
default; any other name needs --allowed-host name:port, and a request
arriving under an unlisted name gets 421 Misdirected Request.
| Tool | What it returns | Parameters |
|---|
get_stock_quote | Current price, change, day and 52-week range, volume, market cap, P/E, EPS, dividend yield | ticker |
get_historical_prices | OHLCV history with summary stats and total return | ticker, period, interval |
get_company_info | Business summary, key executives, valuation and financial highlights | ticker |
get_financial_statements | Annual income statement, balance sheet, and cash flow | ticker |
compare_stocks | Key metrics for multiple tickers side by side, plus quick insights | tickers (2 to 10) |
get_analyst_recommendations | Price targets, consensus, recommendation trend, and recent upgrades/downgrades | ticker |
get_market_news | Latest news headlines with source, date, summary, and link | ticker, count |
get_options_chain | Expiration dates, or the calls/puts chain (strike, bid/ask, volume, OI, IV) | ticker, expiration_date, option_type |
get_holders | Institutional, mutual-fund, or major holders, or insider transactions | ticker, holder_type |
get_dividends_splits | Dividend payment history (with summary) and stock-split history | ticker |
get_analyst_estimates | Forward price targets, EPS/revenue estimates by period, and growth estimates | ticker |
search_symbols | Find ticker symbols by company name or keyword | query, count |
get_market_status | Whether a market is open/closed, with timing and a major-index summary | region |
get_earnings | Next earnings date (days away, EPS and revenue estimates), ex-dividend date, beat/miss history | ticker, limit |
get_earnings_calendar | Every company reporting in a date range, with timing and EPS estimate | start_date, end_date, min_market_cap, limit |
screen_stocks | Results of a Yahoo predefined screener with price, change, relative volume, P/E | screener, count |
get_fund_data | ETF or mutual fund holdings, expense ratio, sector weights, asset classes | ticker |
get_sector_overview | Sector or industry overview, largest companies, industries, top growers and performers | sector, industry, limit |
Every tool also accepts response_format ("markdown", the default, or "json").
Every result also carries the data as MCP structured content, described by the tool's published outputSchema, whichever text format you ask for. Clients that support structured output read typed fields directly; others read the text. Missing figures are null, and a failed call returns isError: true with a message saying what to change.
get_historical_prices options:
period: 1d, 5d, 1mo, 3mo, 6mo, 1y, 2y, 5y, 10y, ytd, max
interval: 1m, 2m, 5m, 15m, 30m, 60m, 90m, 1h, 1d, 5d, 1wk, 1mo, 3mo
get_options_chain: call without expiration_date to list available dates, then again with a date. option_type is calls, puts, or both. A chain returns the strikes nearest the current price.
get_holders: holder_type is institutional, mutualfund, major, insider_transactions, insider_purchases (6-month net insider buying), or insider_roster.
screen_stocks: screener is one of day_gainers, day_losers, most_actives, most_shorted_stocks, small_cap_gainers, aggressive_small_caps, growth_technology_stocks, undervalued_growth_stocks, undervalued_large_caps, top_etfs_us, top_performing_etfs, technology_etfs, bond_etfs, top_mutual_funds, solid_large_growth_funds, solid_midcap_growth_funds, conservative_foreign_funds, high_yield_bond, portfolio_anchors.
get_sector_overview: sector is one of basic-materials, communication-services, consumer-cyclical, consumer-defensive, energy, financial-services, healthcare, industrials, real-estate, technology, utilities. Call without industry to get the list of industry keys.
๐ฌ Example Prompts
Once the server is connected, just ask Claude:
- "What's the current price of Apple stock?"
- "Show me Amazon's stock performance over the last year"
- "Tell me about Tesla as a company and who runs it"
- "Show me Apple's income statement"
- "Compare AAPL, MSFT, and GOOGL"
- "What do analysts think about Amazon, and what's the price target?"
- "What's the latest news on NVIDIA?"
- "Show me the SPY call options expiring next month"
- "Who are the biggest institutional holders of Apple?"
- "What's Coca-Cola's dividend history?"
- "When does NVIDIA report next, and has it been beating estimates?"
- "Which large caps report earnings this week?"
- "What are today's biggest gainers?"
- "What's inside QQQ and what does it cost?"
- "Who are the biggest semiconductor companies?"
- "Are Tesla insiders net buying or selling?"
โ FAQ
Does it need an API key or a paid plan?
No. It reads Yahoo Finance's public data through the yfinance library. There is no key, account or signup.
Is the data real-time?
Quotes are near real-time for most US stocks and can be delayed about 15 minutes on some exchanges. Every quote states its exchange, market state and timestamp.
Which tickers work?
Any symbol Yahoo Finance lists: US stocks (AAPL), class shares (BRK.B or BRK-B), non-US listings with Yahoo's exchange suffix (7203.T, BP.L, SAP.DE), ETFs and mutual funds (SPY, VFIAX), indices (^GSPC), crypto (BTC-USD) and currencies (EURUSD=X). Case does not matter. If you only have a company name, search_symbols finds the ticker.
Can it place trades or change anything?
No. Every tool is read-only.
Does it work with clients other than Claude?
Yes. It speaks standard MCP, so any client that supports MCP over stdio or Streamable HTTP can use it. Setup for the common ones is under Quick Start.
How do agents get structured data?
Every result carries typed structuredContent matching the tool's outputSchema, whatever text format was asked for. Pass response_format: "json" to get JSON text as well.
Where is the machine-readable summary?
llms.txt lists every tool, limit and error behaviour in one page for agents.
๐ Troubleshooting
"Command not found" / "Python not found"
Make sure Python and Node.js are installed and on your PATH. On macOS/Linux, try python3 instead of python in the config.
"Module not found: yfinance" (manual install only)
Install the dependencies:
pip install yfinance curl_cffi pandas tabulate mcp pydantic httpx
Tools not showing up in Claude
- Confirm the config file is valid JSON (no trailing commas).
- Fully quit and reopen Claude Desktop.
- Check the path in your config actually exists.
"Error fetching data"
- Check your internet connection.
- Verify the ticker symbol (for example
AAPL, not Apple).
- Some smaller companies have limited data, and Yahoo Finance can be briefly unavailable.
Using a different model or provider (LiteLLM, OpenRouter, NVIDIA NIM, a local model)
This server never talks to a model. Your client starts it as a local process and
speaks JSON-RPC over stdin/stdout, so changing ANTHROPIC_BASE_URL or swapping the
model behind your client has no effect on it. If tools stop firing after a switch
like that, check two things: the model has to support function calling, and a proxy
configured to drop unsupported parameters can silently strip your tool definitions,
which produces no error at all. Run /mcp in your client (or claude mcp list) to
confirm the server is connected before suspecting the server.
๐ ๏ธ Manual Installation (Alternative)
If you would rather run the Python file directly instead of via npx:
1. Download the server
Save yahoo_finance_mcp.py somewhere on your machine and install the dependencies:
pip install yfinance curl_cffi pandas tabulate mcp pydantic httpx
(or pip3 on macOS/Linux)
2. Point Claude Desktop at it
{
"mcpServers": {
"yahoo-finance": {
"command": "python3",
"args": ["/absolute/path/to/yahoo_finance_mcp.py"]
}
}
}
On Windows use "command": "python" and a path like "C:\\path\\to\\yahoo_finance_mcp.py" (double backslashes or forward slashes).
3. Restart Claude Desktop.
๐ Privacy & Rate Limits
- Uses the free Yahoo Finance API via the
yfinance library.
- Requests go straight to Yahoo Finance. Nothing is stored or proxied.
- Yahoo Finance rate-limits roughly 2,000 requests/hour per IP.
- Intended for personal, educational, and research use.
๐ Notes
- Tickers are case-insensitive, and
BRK.B is accepted as well as Yahoo's BRK-B.
- Some quotes may be delayed 15 to 20 minutes.
- Financial statements are generally available for larger public companies.
๐ Changelog
See CHANGELOG.md for the full version history.
๐ Resources
โ๏ธ Legal Disclaimer
This tool uses Yahoo Finance's publicly available data through the yfinance library. Yahoo!, Y!Finance, and Yahoo! Finance are registered trademarks of Yahoo, Inc. This tool is not affiliated with, endorsed by, or vetted by Yahoo, Inc. Please refer to Yahoo!'s terms of use for details on your rights to use the data.
๐ค Author
Daniel Shashko
๐ License
MIT ยฉ Daniel Shashko