Skip to main content
Glama
yfinance-mcp-ts

yfinance-mcp-ts

by anconina

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

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

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

    A3.6/5.0

    Scored across 20 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count3/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      A
      maintenance
      A simple MCP server for Yahoo Finance using yfinance. This server provides a set of tools to fetch stock data, news, and other financial information.
      2
      15
      211
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      A Model Context Protocol (MCP) server that provides comprehensive access to Yahoo Finance data through 18 specialized tools for pricing, financials, options, holders, and news.
      18
      25 PyPI
      1
      MIT
    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      Financial MCP server providing 15 tools for stock quotes, financials, risk metrics, news sentiment, SEC filings, and session summaries via Yahoo Finance data.
      -