yahoo-finance2

yahoo-finance2 is an unofficial, community-maintained TypeScript client for Yahoo Finance’s public web endpoints. It ships modules for real-time quotes, historical and intraday price charts, full fundamentals (income statements, balance sheets, cash flow, earnings, ownership), stock/company search, screeners, options chains, and trending/insights data, each backed by runtime-validated response schemas so TypeScript consumers get accurate types and a clear error instead of silently malformed data when Yahoo’s response shape drifts.

Beyond the importable library, the project bundles a CLI for ad-hoc terminal queries and an MCP (Model Context Protocol) server plus an installable Agent Skill so LLM agents and tools like Claude, Cursor, and Codex can call the same data directly. It runs on Node 22+, Deno 2+, Bun, and Cloudflare Workers, built and tested from a single Deno-first source tree that’s cross-compiled to a dual CJS/ESM npm package via @deno/dnt.

What You Get

• A single YahooFinance client class exposing quote, historical/chart, search, screener, options, and quoteSummary sub-modules with runtime-validated, typed responses
• A bundled CLI (npx yahoo-finance2) for querying any module directly from the terminal without writing code
• An MCP server and Agent Skill so AI agents (Claude, Cursor, Codex) can call the same Yahoo Finance modules as tools
• Cross-runtime support (Node 22+, Deno 2+, Bun 1+, Cloudflare Workers) built and tested from one shared Deno-first codebase

Common Use Cases

• Pulling real-time or historical price data into a portfolio tracker or trading dashboard
• Fetching company fundamentals (financials, earnings, ownership) for investment research tooling
• Building an LLM agent or chatbot that answers stock-market questions via the MCP server or Agent Skill
• Running quick one-off lookups from the command line during analysis or debugging

Under The Hood

Architecture The library centers on a YahooFinance class (src/createYahooFinance.ts) instantiated with a set of modules merged from src/modules/index.ts and src/other/index.ts; each module (quote.ts, historical.ts, quoteSummary.ts, etc.) declares a query/result schema pair executed uniformly through a shared moduleExec.ts pipeline: validate user options against a JSON-schema definition, merge module defaults/runtime/overrides, optionally transform, dispatch through yahooFinanceFetch.ts (which handles cookie-jar and crumb-token acquisition for endpoints that require it), then validate-and-coerce the raw Yahoo response against a result schema before returning. This separates module-specific behavior (URL, schema keys, transforms) from cross-cutting concerns (validation, fetching, auth), so adding a module means writing a schema plus a thin wrapper rather than duplicating fetch/validation logic; the same YahooFinance instance is reused as the substrate for both the CLI in bin/ and the MCP server in src/mcp/, rather than each surface reimplementing calls independently.

Tech Stack The project is Deno-first (deno.json, TypeScript throughout src/), tested with Deno’s native test runner and standard library (@std/async, @std/fs, @std/path, @std/testing), then cross-compiled to a dual CJS/ESM npm package via @deno/dnt (scripts/build_npm.ts) so it also runs on Node 22+, Bun 1+, and Cloudflare Workers under nodejs_compat. It implements its own JSON-Schema-based validation layer (src/lib/validate, validateAndCoerceTypes.ts) rather than depending on Zod or Ajv, a custom cookie-jar/crumb module for Yahoo’s authentication quirks, and an MCP server built on @modelcontextprotocol/sdk with both stdio and streamable-HTTP transports. Releases are automated with semantic-release plus a JSR-publish plugin and conventional-commits changelog generation.

Code Quality The repo carries an extensive, colocated test suite (37 *.test.ts files covering lib internals like cookieJar, getCrumb, moduleExec, notices, validateAndCoerceTypes, and yahooFinanceFetch, plus module- and index-level tests), run via deno test --parallel against recorded HTTP fixtures (@gadicc/fetch-mock-cache) so tests replay cached Yahoo responses rather than hitting the network live, with a separate Cloudflare Workers-specific test job. CI runs format and lint checks, a full TypeScript type-check across every entry point, a schema-drift check that regenerates JSON schemas and diffs them against what’s committed, and uploads coverage to Codecov. Errors are typed rather than opaque strings (BadRequestError, HTTPError, InvalidOptionsError, FailedYahooValidationError carrying the raw result and validation errors), and both request options and responses are runtime-validated and coerced against schemas so any drift in Yahoo’s API shape surfaces as a specific, catchable error.

What Makes It Unique new YahooFinance() then await yahooFinance.quote('AAPL') is the whole surface for the common case, with per-module named exports available for consumers who want smaller bundles, and options objects documented via JSDoc with runnable examples embedded directly in the module source. What distinguishes it from similar API wrappers is runtime response validation and coercion (a silent Yahoo API shape change throws a typed error instead of returning malformed data), a quoteCombine helper for merging results across multiple module calls, and shipping the same functionality as three surfaces — library import, CLI, and MCP server/Agent Skill — from one codebase, giving agentic tools first-class support without a separate wrapper package.