yfinance-mcp-ts
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@yfinance-mcp-ts show me the latest 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.
Features
20 MCP Tools — stock quotes, financials, options, screeners, research, and market data
LLM-Optimized Output — compact text/markdown responses with auto-aggregation and size guards
Browser Impersonation — TLS fingerprinting bypass via impit for 100% success rate
Proxy Rotation — round-robin rotation with automatic failure tracking and cooldown
Retry with Backoff — exponential backoff with jitter for rate limits and transient errors
300+ Screeners — predefined stock screeners (day gainers, most actives, growth stocks, etc.)
Premium Support — optional Yahoo Finance Premium authentication via Puppeteer
Related MCP server: yfinance
Installation
npm install yfinance-mcp-tsMCP Server Setup
Claude Desktop / Claude Code
Add to your config (~/.config/claude/claude_desktop_config.json on macOS/Linux, %APPDATA%\Claude\claude_desktop_config.json on Windows):
{
"mcpServers": {
"yfinance": {
"command": "npx",
"args": ["yfinance-mcp-ts"]
}
}
}With proxy rotation:
{
"mcpServers": {
"yfinance": {
"command": "npx",
"args": ["yfinance-mcp-ts"],
"env": {
"YFINANCE_PROXY_LIST": "http://user:pass@proxy1.com:8080\nhttp://user:pass@proxy2.com:8080"
}
}
}
}You can also run the server manually:
npm run mcp # production
npm run mcp:dev # development (ts-node)
npx yfinance-mcp-ts # from npmAvailable Tools
Tool | Description |
Stock Data | |
| Current price, market cap, volume |
| P/E ratio, 52-week range, dividend yield |
| Company info, sector, employees |
| Historical OHLCV data |
| Income statement, balance sheet, cash flow |
| Options chain with Greeks |
| Forward P/E, PEG, beta, EPS |
| Analyst recommendations |
| EPS estimates and actuals |
Screeners | |
| List all 300+ screeners |
| Run a screener |
| Get screener details |
Research | |
| Upcoming earnings announcements |
| Upcoming and recent IPOs |
| Upcoming and recent stock splits |
Market Data | |
| Search by name or symbol |
| Major indices (S&P 500, Dow, NASDAQ) |
| Trending stocks |
| Currency pairs and exchange rates |
| Supported countries list |
All tools return compact text by default. Add format: "json" to any call for raw JSON output.
Environment Variables
Variable | Description | Default |
|
|
|
| Enable HTTP/3 (impit only) |
|
| Ignore TLS certificate errors |
|
| Request timeout (ms) |
|
| Newline-separated proxy URLs | — |
| Failures before marking proxy unhealthy |
|
| Cooldown before retrying unhealthy proxy (ms) |
|
| Enable automatic retry |
|
| Max retry attempts |
|
| Initial retry delay (ms) |
|
| Max retry delay (ms) |
|
Library Usage
Ticker
import { Ticker } from 'yfinance-mcp-ts';
const ticker = new Ticker('AAPL');
// or multiple: new Ticker('AAPL MSFT GOOG') / new Ticker(['AAPL', 'MSFT'])
await ticker.getPrice();
await ticker.getSummaryDetail();
await ticker.getSummaryProfile();
await ticker.getKeyStats();
await ticker.getEarnings();
await ticker.getRecommendationTrend();
// Historical data
await ticker.getHistory({ period: '1mo', interval: '1d' });
await ticker.getHistory({ start: '2024-01-01', end: '2024-12-31', interval: '1wk' });
// Financial statements ('a' = annual, 'q' = quarterly)
await ticker.getIncomeStatement('a');
await ticker.getBalanceSheet('q');
await ticker.getCashFlow('a');
await ticker.getFinancials('income', 'a'); // type: 'income' | 'balance' | 'cash' | 'cashflow'
// Options
await ticker.getOptionChain();
// All available modules at once
await ticker.getAllModules();Method | Description |
| Current price and market data |
| Summary statistics |
| Company profile |
| Detailed company info |
| Key statistics |
| Financial KPIs |
| Earnings data |
| Earnings trend |
| Upcoming events |
| Analyst recommendations |
| ESG metrics |
| Major shareholders |
| Insider holdings |
| Insider transactions |
| Institutional ownership |
| Fund ownership |
| SEC filings |
| Quote type info |
| Upgrade/downgrade history |
| Historical OHLCV data |
| Dividend history |
| Income statement |
| Balance sheet |
| Cash flow statement |
| Valuation measures |
| All financial data |
| Full options chain |
| Quick quotes |
| Similar stocks |
| Technical analysis |
| Recent news |
| Company executives |
Fund-specific: getFundHoldingInfo(), getFundTopHoldings(), getFundSectorWeightings(), getFundBondHoldings(), getFundEquityHoldings(), getFundBondRatings(), getFundPerformance(), getFundProfile()
Screener
import { Screener } from 'yfinance-mcp-ts';
const screener = new Screener();
screener.availableScreeners; // list all 300+ screener IDs
screener.getScreenerInfo('day_gainers'); // screener metadata
await screener.getScreeners('day_gainers', 25); // run with result count
await screener.getScreeners('day_gainers most_actives', 10); // multipleResearch
import { Research } from 'yfinance-mcp-ts';
const research = new Research();
await research.getEarnings('2024-01-01', '2024-01-31');
await research.getSplits('2024-01-01', '2024-12-31');
await research.getIPOs('2024-01-01', '2024-12-31');
// Premium only
await research.getReports(100, { sector: 'Technology', investment_rating: 'Bullish' });
await research.getTrades(100, { trend: 'Bullish', term: 'Short term' });Standalone Functions
import { search, getMarketSummary, getTrending, getCurrencies, getValidCountries } from 'yfinance-mcp-ts';
await search('Apple', { quotesCount: 10, newsCount: 5 });
await search('AAPL', { firstQuote: true });
await getMarketSummary('united states');
await getTrending('united states');
await getCurrencies();
getValidCountries(); // ['united states', 'france', 'germany', ...]Configuration
const ticker = new Ticker('AAPL', {
country: 'united states', // 14 supported countries
timeout: 30000,
httpClient: 'impit', // 'impit' (default) or 'axios'
retry: {
enabled: true,
maxRetries: 3,
initialDelay: 1000,
maxDelay: 30000,
},
proxyRotation: {
proxyList: 'http://proxy1:8080\nhttp://proxy2:8080',
maxFailures: 3,
cooldownMs: 300000,
},
// Premium auth (requires puppeteer)
username: 'your@email.com',
password: 'password',
});Supported countries: united states, australia, canada, france, germany, hong kong, india, italy, spain, united kingdom, brazil, new zealand, singapore, taiwan
Requirements
Node.js >= 20.0.0
TypeScript >= 5.0 (for development)
puppeteer>= 21.0.0 (optional, for premium features)https-proxy-agent/socks-proxy-agent(optional, for proxy support)
License
MIT
Credits
TypeScript port of yahooquery by Doug Guthrie.
Disclaimer
Not affiliated with Yahoo, Inc. Data is for personal use only. Review Yahoo's terms of service before using in production.
Available Tools
20 toolsget_currenciesA
Returns available currency pairs as a compact table. Use to find forex pair symbols. Text default; set format=json for structured data.
Inputs: format, max_results.
get_earningsA
Returns EPS history with surprise %, next estimate, and revenue trend. Use for earnings analysis and surprise tracking. Text default; set format=json for structured data.
Inputs: symbols (required), format.
get_earnings_calendarA
Returns upcoming earnings announcements with EPS estimates as a table. Use for tracking reporting dates across the market. Text default; set format=json for structured data.
Inputs: end, start, format, max_results.
get_financialsB
Returns financial statements with key metrics and YoY% changes. Default: summary mode (top metrics); use detail=full for all. Text default; set format=json for structured data.
Inputs: symbols (required), type, detail, format, +1 more.
get_iposB
Returns upcoming and recent IPO listings with pricing and deal details. Use for tracking new market listings. Text default; set format=json for structured data.
Inputs: end, start, format, max_results.
get_key_statsA
Returns advanced statistics (PEG, beta, EV ratios, margins, growth). Use for deep fundamental analysis beyond get_stock_summary. Text default; set format=json for structured data.
Inputs: symbols (required), format.
get_market_summaryA
Returns major market indices with price, change, and percent change. Use for broad market overview. Text default; set format=json for structured data.
Inputs: format, country.
get_optionsA
Returns option chain with ATM-anchored strike window. Default: nearest 3 expirations summary; use expiration param for specific chain. Text default; set format=json for structured data.
Inputs: symbol (required), type, detail, format, +2 more.
get_recommendationsA
Returns analyst consensus and 4-month recommendation trend. Use for sentiment analysis on a stock. Text default; set format=json for structured data.
Inputs: symbols (required), format.
get_screenerA
Runs a stock screener and returns top results as a compact table. Use list_screeners first to find screener names. Text default; set format=json for structured data.
Inputs: screener (required), count, fields, format.
get_screener_infoA
Returns detailed metadata about a specific screener including criteria. Use to understand what a screener filters before running it. Returns JSON.
Inputs: screener (required).
get_splitsA
Returns upcoming and recent stock splits with ratios. Use for tracking share split events. Text default; set format=json for structured data.
Inputs: end, start, format, max_results.
get_stock_historyB
Returns historical OHLCV data with auto-aggregation and stats. Use for price trends and technical analysis. Text default; set format=json for structured data.
Inputs: symbols (required), end, start, format, +5 more.
get_stock_priceA
Returns current price, change, market cap, and volume. Use for quick price checks; use get_stock_summary for valuation metrics. Text default; set format=json for structured data.
Inputs: symbols (required), format.
get_stock_profileA
Returns company profile (sector, industry, summary, governance). Use for company overview; set include_officers=true for executives. Text default; set format=json for structured data.
Inputs: symbols (required), format, include_officers.
get_stock_summaryA
Returns valuation and trading metrics (P/E, yield, ranges, volume, bid/ask). Use for fundamental screening; use get_key_stats for advanced ratios. Text default; set format=json for structured data.
Inputs: symbols (required), format.
get_supported_countriesA
Returns list of supported countries for market data and screeners. Use to find valid country codes for other tools. Returns JSON.
Inputs: no named parameters.
get_trendingB
Returns currently trending/most watched stock symbols. Use to find popular stocks before deeper analysis. Returns JSON.
Inputs: count, country.
list_screenersA
Lists available stock screeners organized by category. Use to discover screener names before calling get_screener. Text default; set format=json for structured data.
Inputs: format, category.
search_stocksA
Searches for stocks by company name or symbol. Use to find ticker symbols before calling other tools. Returns JSON.
Inputs: query (required), limit.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Tools are mostly distinct with clear separation between price, summary, key stats, and financials; descriptions cross-reference each other to guide selection. However, several fundamental tools (get_stock_summary, get_key_stats, get_financials) have overlapping valuation concepts that require careful reading to disambiguate.
All tool names follow a consistent snake_case verb_noun pattern (get_, list_, search_) with no mixed conventions. The verb is predictable by action type, making the naming scheme easy to scan and remember.
At 20 tools, the set is on the heavy side for a single data-retrieval server, and some tools could be consolidated (e.g., stock summary, key stats, and financials). However, each tool maps to a distinct yfinance endpoint, so the count is defensible but borderline.
The surface covers a broad range of market data: prices, fundamentals, options, screeners, earnings, IPOs, currencies, and market overview. Minor gaps remain (dividends, news, holder data), but core workflows are well supported.
Maintenance
Related MCP Connectors
MCP server for Financial Modeling Prep API with 250+ financial data tools
Hosted MCP server for Indian NSE/BSE stock research: 59 tools for quotes, financials and ratios, peers, shareholding and pledge, filings with extracted facts, screens, F&O and FII/DII context. Source and freshness on every answer; no buy/sell calls.
MCP server for stocksense-ai documentation, generated by doc2mcp.
Financial data and analysis tools for Turkish BIST and international markets via MCP.
Related MCP Servers
- AlicenseAqualityAmaintenanceA simple MCP server for Yahoo Finance using yfinance. This server provides a set of tools to fetch stock data, news, and other financial information.215211MIT
- AlicenseAqualityDmaintenanceA Model Context Protocol (MCP) server that provides comprehensive access to Yahoo Finance data through 18 specialized tools for pricing, financials, options, holders, and news.1825 PyPI1MIT
- FlicenseNot gradedqualityNot gradedmaintenanceFinancial MCP server providing 15 tools for stock quotes, financials, risk metrics, news sentiment, SEC filings, and session summaries via Yahoo Finance data.-
- FlicenseNot gradedqualityDmaintenanceA lightweight MCP server for accessing Yahoo Finance data, providing stock prices, history, company information, and financial statements.-