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

| 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.