yfinance-mcp-server

Exposes yfinance's stock ticker data fetching through MCP server tools, allowing Claude and other MCP clients to query current and historical stock prices by ticker symbol. Implements MCP tool schema binding that translates natural language requests into yfinance API calls, handling ticker validation and price data serialization back to the client as structured JSON responses.

Retrieves multi-period historical OHLCV (open, high, low, close, volume) data for a given ticker and date range, aggregating yfinance responses into structured time-series format. Handles date range validation, period granularity selection (daily, weekly, monthly), and formats output as JSON arrays or CSV-compatible structures suitable for analysis or downstream processing.

Fetches company-level metadata and fundamental metrics (market cap, P/E ratio, dividend yield, sector, industry, 52-week high/low) from yfinance's Ticker object, exposing these as MCP tools. Implements lazy-loading of ticker info to minimize network requests, caching metadata within a single MCP session, and serializing complex objects (e.g., company info dictionaries) into JSON-safe formats.

Retrieves historical dividend payments and earnings dates for a ticker using yfinance's dividends and earnings attributes, formatting them as time-indexed JSON arrays. Handles missing data gracefully (some tickers have no dividend history), validates date ranges, and provides both raw dividend amounts and calculated metrics like dividend yield and payout frequency.

Retrieves historical stock splits and corporate actions (reverse splits, mergers, spinoffs) from yfinance's splits attribute, providing adjusted share counts and split ratios. Implements date-indexed lookup allowing clients to understand historical share count changes and their impact on price comparisons across split events.

Enables MCP clients to request data for multiple tickers in a single logical operation by composing individual ticker tools into batch queries, handling parallel or sequential fetching depending on MCP client implementation. Implements error handling per ticker (one failure doesn't block others) and aggregates results into a unified response structure suitable for comparative analysis.

Implements the Model Context Protocol (MCP) server specification, automatically generating tool schemas for all yfinance capabilities and exposing them via MCP's tool-calling interface. Handles MCP request/response serialization, tool discovery, and parameter validation according to MCP spec, allowing any MCP-compatible client (Claude, custom agents) to discover and invoke yfinance tools without prior knowledge of their signatures.