Yfinance Ts

A TypeScript wrapper for the Yahoo Finance API with a built-in MCP server for AI agents like Claude.

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

Installation

npm install yfinance-mcp-ts

MCP 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:[email protected]:8080\nhttp://user:[email protected]:8080"
      }
    }
  }
}

You can also run the server manually:

npm run mcp          # production
npm run mcp:dev      # development (ts-node)
npx yfinance-mcp-ts  # from npm

Available Tools

Tool	Description
Stock Data
get_stock_price	Current price, market cap, volume
get_stock_summary	P/E ratio, 52-week range, dividend yield
get_stock_profile	Company info, sector, employees
get_stock_history	Historical OHLCV data
get_financials	Income statement, balance sheet, cash flow
get_options	Options chain with Greeks
get_key_stats	Forward P/E, PEG, beta, EPS
get_recommendations	Analyst recommendations
get_earnings	EPS estimates and actuals
Screeners
list_screeners	List all 300+ screeners
get_screener	Run a screener
get_screener_info	Get screener details
Research
get_earnings_calendar	Upcoming earnings announcements
get_ipos	Upcoming and recent IPOs
get_splits	Upcoming and recent stock splits
Market Data
search_stocks	Search by name or symbol
get_market_summary	Major indices (S&P 500, Dow, NASDAQ)
get_trending	Trending stocks
get_currencies	Currency pairs and exchange rates
get_supported_countries	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
YFINANCE_HTTP_CLIENT	impit or axios	impit
YFINANCE_HTTP3	Enable HTTP/3 (impit only)	false
YFINANCE_IGNORE_TLS_ERRORS	Ignore TLS certificate errors	false
YFINANCE_TIMEOUT	Request timeout (ms)	30000
YFINANCE_PROXY_LIST	Newline-separated proxy URLs	—
YFINANCE_PROXY_MAX_FAILURES	Failures before marking proxy unhealthy	3
YFINANCE_PROXY_COOLDOWN_MS	Cooldown before retrying unhealthy proxy (ms)	300000
YFINANCE_RETRY_ENABLED	Enable automatic retry	true
YFINANCE_RETRY_MAX_RETRIES	Max retry attempts	5
YFINANCE_RETRY_INITIAL_DELAY	Initial retry delay (ms)	2000
YFINANCE_RETRY_MAX_DELAY	Max retry delay (ms)	60000

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();

All Ticker methods

Method	Description
getPrice()	Current price and market data
getSummaryDetail()	Summary statistics
getSummaryProfile()	Company profile
getAssetProfile()	Detailed company info
getKeyStats()	Key statistics
getFinancialDataSummary()	Financial KPIs
getEarnings()	Earnings data
getEarningsTrend()	Earnings trend
getCalendarEvents()	Upcoming events
getRecommendationTrend()	Analyst recommendations
getEsgScores()	ESG metrics
getMajorHolders()	Major shareholders
getInsiderHolders()	Insider holdings
getInsiderTransactions()	Insider transactions
getInstitutionOwnership()	Institutional ownership
getFundOwnership()	Fund ownership
getSecFilings()	SEC filings
getQuoteType()	Quote type info
getGradingHistory()	Upgrade/downgrade history
getHistory()	Historical OHLCV data
getDividendHistory()	Dividend history
getIncomeStatement()	Income statement
getBalanceSheet()	Balance sheet
getCashFlow()	Cash flow statement
getValuationMeasures()	Valuation measures
getAllFinancialData()	All financial data
getOptionChain()	Full options chain
getQuotes()	Quick quotes
getRecommendations()	Similar stocks
getTechnicalInsights()	Technical analysis
getNews()	Recent news
getCompanyOfficers()	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); // multiple

Research

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: '[email protected]',
  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.