Skip to main content
Glama
yfinance-mcp

yfinance-mcp

by LurigeLars

yfinance-mcp

CI CodeQL Python License

A small, read-only Model Context Protocol (MCP) server for Yahoo Finance news and options-market research through the upstream yfinance package.

It gives AI clients a bounded, typed way to inspect option chains, positioning/activity summaries, theoretical greeks, gamma concentration, scenario analysis and Yahoo Finance news without turning the MCP into a generic market-data or brokerage interface.

Not execution infrastructure. Yahoo Finance data can be delayed or incomplete. Quotes, open interest and model outputs are analytical context, not broker-grade or execution-grade data.

Why this project exists

The upstream yfinance package is useful for Python applications, but an AI agent needs a different interface:

  • a small set of explicit tools rather than arbitrary library access.

  • bounded responses so option chains and news cannot grow without control.

  • normalized output with predictable semantics.

  • deterministic summaries that do not depend on free-form model interpretation.

  • clear separation between observed market data and theoretical calculations.

  • no brokerage login, account access or order execution.

This server is intentionally narrow. It exists primarily to fill two research gaps:

  1. Options-market structure — expirations, chains, volume/open-interest structure, IV summaries, theoretical greeks, unsigned gamma concentration and bounded scenarios.

  2. Yahoo Finance news discovery — compact per-symbol and batch discovery with source provenance preserved.

It is not intended to become a general Yahoo Finance MCP for quotes, fundamentals, portfolio management or trading.

Related MCP server: polygon-mcp

What it can do

Area

Capability

News

Discover recent Yahoo Finance news for one symbol or a bounded symbol batch

Expirations

List available option expiration dates

Chains

Read calls, puts or both for one expiration

Positioning

Summarize call/put volume, OI, ratios, IV and notable strikes

Surface

Compare a bounded sequence of expirations

Activity

Rank contracts by volume/OI, volume or open interest

Greeks

Calculate Black-Scholes-Merton theoretical greeks

Risk map

Rank unsigned gamma concentration by strike

Scenarios

Reprice contracts under explicit spot, IV and time changes

Everything is read-only.

What it deliberately does not do

  • brokerage authentication.

  • portfolio or account access.

  • order placement or execution.

  • realtime streaming.

  • generic Yahoo quote/fundamental coverage.

  • claims about trade aggressor side, sweeps or opening/closing flow.

  • inference of dealer long/short gamma from open interest alone.

Those boundaries are deliberate. New tools should solve a concrete research gap rather than merely expose another upstream endpoint.

Architecture

MCP client
   |
   v
yfinance-mcp
   |
   +--> bounded news normalization
   |
   +--> options service / deterministic analytics
   |
   v
upstream yfinance package
   |
   v
Yahoo Finance

For remote deployments, an optional gateway can sit in front of the loopback MCP server:

remote MCP client
   -> Cloudflare Access
   -> yfinance gateway
   -> loopback yfinance-mcp HTTP server
   -> yfinance / Yahoo Finance

The public gateway exposes only the reviewed tool allowlist and does not add credentials or brokerage capability.

Data source and limitations

yfinance is an independent open-source library that retrieves data from Yahoo Finance. This project is not affiliated with Yahoo, Yahoo Finance or the yfinance project.

Important limitations:

  • Yahoo Finance option quotes may be delayed.

  • Open interest is not a tick-by-tick realtime signal.

  • A high volume/OI ratio does not by itself establish unusual institutional flow.

  • Yahoo data does not reveal aggressor side or reliably distinguish opening from closing option trades.

  • Missing values remain unknown; they are not silently converted to zero.

  • Retrieval time is not the same thing as market timestamp.

Use venue or broker data when execution quality matters.

The yfinance project notes that Yahoo Finance data is intended for personal use and that users are responsible for complying with Yahoo's terms. Review the upstream yfinance documentation and Yahoo terms before using downloaded data beyond personal research.

Quick start

Requirements

  • Python 3.12+

  • uv

  • no API key or account credentials

Clone and install the locked environment:

git clone https://github.com/LurigeLars/yfinance-mcp.git
cd yfinance-mcp
uv sync --locked

Run over stdio:

uv run yfinance-mcp

Example MCP configuration:

{
  "mcpServers": {
    "yfinance": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/yfinance-mcp",
        "--locked",
        "yfinance-mcp"
      ]
    }
  }
}

Tool catalog

The server exposes ten bounded read-only tools.

news_get

Returns up to 50 Yahoo Finance news items for one symbol.

Output is normalized to fields such as publisher, publication timestamp, canonical URL, upstream ID, related tickers and content type. Treat this as discovery data: material claims should be verified against primary sources or authoritative wires.

news_batch

Queries up to 100 unique symbols with an explicit per-symbol bound.

Partial upstream failures are returned explicitly in failed_symbols; successful symbols are retained. Syndicated duplicates are intentionally left for downstream canonicalization.

option_expirations

Returns the expiration dates Yahoo Finance currently exposes for an optionable symbol.

option_chain

Returns calls, puts or both for one expiration, including available upstream fields such as:

  • contract symbol.

  • last trade date.

  • strike.

  • last price.

  • bid / ask.

  • volume.

  • open interest.

  • implied volatility.

  • in-the-money flag.

  • contract size.

  • currency.

Optional filters can narrow strike, volume and open-interest ranges. There is no hidden default row limit. limit_per_side is available when the caller explicitly wants a bounded response.

Underlying quote metadata is projected into a small allowlisted schema rather than forwarding Yahoo's full auxiliary payload.

option_positioning_summary

Produces a compact per-expiration summary with:

  • total call and put volume.

  • total call and put open interest.

  • put/call volume and OI ratios.

  • highest-volume strikes.

  • highest-OI strikes.

  • highest volume/OI contracts where OI is positive.

  • IV distribution statistics.

  • underlying quote metadata.

Absolute volume and OI are retained beside ratios so a large ratio cannot hide a tiny denominator.

option_surface_summary

Summarizes a bounded consecutive expiration window (default 8, maximum 12), including:

  • days to expiry.

  • call/put volume and OI totals.

  • put/call ratios.

  • median IV by side.

  • nearest-to-spot strike with call/put IV.

  • highest combined-OI strikes.

start_index pages through the expiration list and the response preserves the explicit selection bound.

option_activity_summary

Ranks contracts across a bounded expiration window using explicit minimum volume and open-interest thresholds.

Ranking can use:

  • volume/OI ratio.

  • absolute volume.

  • absolute open interest.

The output includes contract-level bid/ask, IV, strike distance from spot and last-trade timestamp.

This is activity evidence, not directional order flow.

option_greeks

Calculates Black-Scholes-Merton theoretical:

  • price.

  • delta.

  • gamma.

  • theta per day.

  • vega per IV point.

  • rho per rate point.

The annualized risk-free rate is an explicit input. Continuous dividend yield defaults to zero.

spot_override lets callers supply a fresher underlying price from another source instead of relying on Yahoo's potentially delayed regular-market quote.

option_risk_map

Weights model gamma by open interest and contract multiplier to rank strike-level gamma concentration.

The result is deliberately unsigned. Open interest does not reveal who is long or short, so the server does not label this "dealer gamma" or infer dealer direction.

The tool also returns a simple one-standard-deviation ATM implied move from available contract IVs.

option_scenario

Reprices a bounded single-expiration contract set under explicit changes to:

  • underlying spot.

  • implied volatility, expressed as absolute volatility points.

  • time forward.

Contracts can be ranked by open interest, absolute model-price change or unsigned gamma concentration.

These are theoretical model changes, not executable P&L forecasts.

Model assumptions

The theoretical options analytics use Black-Scholes-Merton with ACT/365 and assume expiry at 16:00 America/New_York.

US equity and ETF options are generally American-style, so this is an approximation. The model does not capture, among other things:

  • early exercise.

  • discrete dividend timing.

  • borrow constraints.

  • full volatility-surface dynamics.

  • market microstructure.

Use spot_override with a fresher underlying price when available, and use venue or broker quotes for execution decisions.

HTTP mode

The same tool surface can run over Streamable HTTP:

uv run yfinance-mcp-http

Default endpoint:

http://127.0.0.1:8772/mcp

Environment variables:

  • YFINANCE_MCP_HOST — bind host.

  • YFINANCE_MCP_PORT — bind port.

  • YFINANCE_MCP_ALLOW_NON_LOOPBACK=1 — explicit opt-in required for a non-loopback bind.

A non-loopback host is rejected unless that opt-in is set.

Windows background task

The included installer creates a per-user, limited-privilege Scheduled Task and keeps the HTTP server on loopback:

.\scripts\windows\install-http-task.ps1

When the local Docker-MCP host-port registry is present, the installer reserves a stable port for yfinance-mcp-http rather than silently moving the service between ports.

A bounded live provider smoke test is available after installation:

.\.venv\Scripts\python.exe .\scripts\smoke_options.py NVDA

Protected remote gateway

Do not expose the unauthenticated Python MCP HTTP endpoint directly to the Internet.

A separate Node gateway is included for deployments protected by Cloudflare Access. It:

  • validates the Access JWT independently.

  • strips client credentials before forwarding.

  • exposes only the ten reviewed read-only tools.

  • applies request/rate limits.

  • compacts MCP schemas/results for model use.

  • keeps the Python MCP endpoint on loopback.

Copy the example environment file:

Copy-Item public\gateway.env.example public\gateway.env

Fill in deployment-specific Access values, keep the real file ignored, then install the gateway:

.\scripts\windows\install-public-gateway.ps1 -AccessAudience <audience>

No real hostname, identity, audience, tunnel ID, token or credential belongs in Git.

Development

Install development dependencies:

uv sync --locked --extra dev

Run lint and tests:

uv run --no-sync ruff check .
uv run --no-sync pytest
node --test tests/gateway/*.test.mjs

The repository runs:

  • CI on Python 3.12 and 3.13.

  • gateway tests.

  • static analysis.

  • CodeQL.

  • Dependabot.

  • a scheduled upstream watch for locked yfinance and FastMCP releases.

Dependency updates should continue through normal review rather than by vendoring upstream yfinance code into this repository.

Security and privacy

This repository is public.

Do not commit:

  • credentials or access tokens.

  • cookies.

  • personal identifiers or email addresses.

  • workstation-specific paths.

  • private domains/endpoints.

  • Cloudflare tunnel identifiers.

  • brokerage or account data.

See SECURITY.md for vulnerability reporting.

License

Apache-2.0 for this MCP wrapper. Market data retrieved from Yahoo Finance remains subject to the applicable upstream data terms.

Available Tools

8 tools
option_activity_summaryOption Activity SummaryC
Read-onlyIdempotent

Rank bounded multi-expiry option activity without inferring trade direction.

Inputs: symbol (required), top_n, sort_by, min_volume, +3 more. Returns: object

option_chainOption ChainC
Read-onlyIdempotent

Return a filtered contract-level option chain for one expiration.

Inputs: expiry (required), symbol (required), max_strike, min_strike, +4 more. Returns: object

option_expirationsOption ExpirationsC
Read-onlyIdempotent

Return available option expiration dates for a symbol.

Inputs: symbol (required). Returns: object

option_greeksOption GreeksC
Read-onlyIdempotent

Return Black-Scholes-Merton theoretical prices and greeks for one expiry.

Inputs: expiry (required), symbol (required), risk_free_rate (required), max_strike, +6 more. Returns: object

option_positioning_summaryOption Positioning SummaryB
Read-onlyIdempotent

Summarize volume, open interest, IV and concentration for one expiration.

Inputs: expiry (required), symbol (required), top_n, max_strike, +1 more. Returns: object

option_risk_mapOption Risk MapB
Read-onlyIdempotent

Map unsigned OI-weighted gamma concentration without inferring dealer direction.

Inputs: expiry (required), symbol (required), risk_free_rate (required), top_n, +6 more. Returns: object

option_scenarioOption ScenarioC
Read-onlyIdempotent

Stress one option expiry across spot, IV and time using Black-Scholes-Merton.

Inputs: expiry (required), symbol (required), risk_free_rate (required), spot_change_pct (required), +11 more. Returns: object

option_surface_summaryOption Surface SummaryC
Read-onlyIdempotent

Summarize option positioning across up to 12 consecutive expirations.

Inputs: symbol (required), top_n, start_index, max_expiries. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 8 tools

    Disambiguation4/5

    Most tools have clear distinct purposes, but the three summary tools (option_positioning_summary, option_surface_summary, option_activity_summary) overlap significantly in scope and could be confused despite the descriptions clarifying expiry ranges and ranking intent.

    Naming Consistency5/5

    All tool names follow a consistent option_ prefix with snake_case, using predictable noun-based naming that is easy to parse and remember.

    Tool Count5/5

    Eight tools is well-scoped for an options analytics server, with each tool covering a distinct analytical aspect without excessive redundancy.

    Completeness3/5

    The set covers core options analytics (expirations, chain, greeks, risk, scenario), but as a yfinance-mcp server it lacks any tools for underlying stock quotes, historical prices, or fundamentals, which are notable gaps for the implied broad financial domain.

    Maintenance

    ActivityActive
    ResponsivenessUsually handled

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables advanced options analysis and strategy evaluation through Yahoo Finance data. Supports calculating Greeks, analyzing risk metrics, and evaluating credit spreads, cash secured puts, and covered calls strategies.
      MIT
    • A
      license
      C
      quality
      D
      maintenance
      Enables querying real-time and historical financial market data for stocks, options, forex, and crypto, including quotes, trades, technical indicators, and reference data through a set of MCP tools.
      71
      3
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables querying stock data, financial information, news, and historical prices from Yahoo Finance through a set of MCP tools.
      5
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides real-time quotes, historical OHLCV data, options chains, news, and multi-ticker comparisons to any MCP client via Yahoo Finance.
      MIT