Yfinance MCP Ts

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: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 npm

Available Tools

All tools return compact text by default. Add format: "json" to any call for raw JSON output.

Environment Variables

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

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