# yahoo-finance2: an unofficial Yahoo Finance client with a CLI, MCP and a skill

> yahoo-finance2 is an MIT licensed TypeScript client for Yahoo Finance, published on npm and usable from Node, Bun, Deno and Cloudflare Workers, with a command line interface, MCP tools for agent clients, an Agent Skill, and typed modules for quotes, charts, options and fundamentals. The judgement is that the packaging is the strongest part, and that the legal position and the delisting behaviour are the two things to read before you build on it.

**gadicc/yahoo-finance2** — Unofficial API for Yahoo Finance with CLI, MCP and Agent Skill

- Repository: https://github.com/gadicc/yahoo-finance2
- Website: https://www.npmjs.com/package/yahoo-finance2
- Stars: 808 · Forks: 109
- Language: HTML
- License: MIT
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/gadicc-yahoo-finance2

## The disclaimer is the first thing in the README

This project is not created or endorsed by Yahoo Inc., and the README says that plainly. Yahoo does not provide any official API to developers, nor does it make any guarantees regarding service availability or API consistency. The counterweight is history, since in practice the open source community has kept this project and its predecessor working well since 2013. The risk statement is equally plain. There are no guarantees, you use the package at your own risk, the developers and Yahoo cannot be held responsible for losses incurred from using the service, and using the package counts as acknowledgement and acceptance of the terms and the licence. For a tool that scrapes somebody else's public endpoints, that framing is the honest one, and it is also the reason the project deserves to be read as a well-maintained community effort rather than a supported API.

## Three ways in: command line, MCP and a skill

The distribution story is the most interesting part of the project, because the same client is exposed three ways. The command line interface is the first, and it covers search, quotes and detailed summaries:

```bash
$ npx yahoo-finance2 --help
$ npx yahoo-finance2 search AMZN
$ npx yahoo-finance2 quoteSummary GOOGL
$ npx yahoo-finance2 quoteSummary NVDA '{"modules":["assetProfile", "secFilings"]}'

# or install it
$ npm install -g yahoo-finance2
$ yahoo-finance search MSFT '{ "someOption": true }'
```

The second is MCP, and the MCP documentation explains how to expose the yahoo-finance2 tools to MCP clients such as Codex, Claude, Cursor and VS Code. The third is the Agent Skill, an Agent Skills compatible skill shipped in the repository under skills/yahoo-finance2 with its own SKILL.md, installed with:

```bash
npx skills add gadicc/yahoo-finance2
```

The npm package also includes that skill for tools that sync skills from installed packages, which removes the need to vendor a copy of the skill definition.

## Typed modules and the search surface

The library form is a default export and a constructor, followed by ordinary async calls:

```ts
// or: const YahooFinance = require("yahoo-finance2").default;
import YahooFinance from "yahoo-finance2";

const yahooFinance = new YahooFinance();

const results = await yahooFinance.search("Apple");

const quote = await yahooFinance.quote('AAPL');
const { regularMarketPrice as price, currency } = quote;
```

The module list is long and specific, with chart, fundamentalsTimeSeries, historical, insights, options, quote, quoteSummary, recommendationsBySymbol, screener, search and trendingSymbols, plus a quoteCombine extra. quoteSummary carries a large set of submodules of its own, from assetProfile and balanceSheetHistory through earnings, financialData, fundPerformance, insiderTransactions, secFilings, summaryProfile and upgradeDowngradeHistory. The documentation is published on jsr.io, and the README points at both the explanatory documentation and the full API reference. TypeScript users get type checking and auto completion, which the README presents with a short animated demonstration.

## The delisting behaviour is the sharpest edge

Two warnings in the README deserve to be quoted rather than paraphrased. The first is the instruction to read the notes on error handling, and the second is what those notes say about delisting. If a stock gets delisted, Yahoo removes all related data, including historical and chart data from periods before the delisting occurred, which means queries that worked before will start failing and there is no way to retrieve that data again. For a project that stores or charts long histories, that is a data availability problem outside your control, and it argues for keeping your own copy of anything you need to keep. The second is the browser limitation, since the README states it is not possible to run this in the browser due to CORS and cookie issues, and the recommendation is to execute calls on a server or in a serverless or edge function and pass the data to the browser as required, using React Server Components, trpc or other strategies to maintain types.

## Bun, Cloudflare, Deno and Node are the supported runtimes

The supported runtime list is unusual for a package of this kind and it tells you where the project expects to be used. Bun v1 and later is supported. Cloudflare is supported on modern releases and tested in CI through Workers Vitest under the nodejs_compat setting, which is a real compatibility promise rather than a claim, since it is checked on every build. Deno v2 and later is supported. Node v22 and later is supported, with the support window following the Node.js release schedule, v22 until 2027-04-30 and v24 until 2028-04-30, and the README links endoflife.date to make the point that the floors move with Node. The repository reinforces this with a deno.json and deno.lock at the top level, so the Deno path is a first class target rather than an afterthought.

## Version 4, and the rename you will trip over

The README opens by telling you which version you are reading, that these are the v4 docs, the current major version published as yahoo-finance2@latest, and that the older v3 docs are in the 3.x branch. Upgrading is handled by a document called UPGRADING.md. Then there is the naming history, which matters for anyone with an existing install. The repository was recently renamed from node-yahoo-finance2 to yahoo-finance2, and the branches were renamed, master to main and devel to dev, with the git commands to update a local installation in the dev section of the upgrade guide. The default branch for the project is now dev, and the CI badge in the README points at the dev branch, so the workflow that builds the tests runs against the development line rather than a release branch. The copyright line reads 2021 by Gadi Cohen and Pilwon Huh, and the licence is MIT.

## The repository, the tooling and the release rhythm

The tree shows a project with real automation around it. There is src for the TypeScript source, bin for the command line entry points, docs for the explanatory and CLI and MCP documentation, tests, the skills directory, scripts, a plans directory, and a set of configuration files including deno.json, release.config.mjs for semantic release, renovate.json for dependency updates, skills-lock.json, an .editorconfig, and agent oriented directories in .agents and .claude alongside AGENTS.md. Releases are frequent and semantic, with v4.0.2 on 2026-08-09, v4.0.3 on 2026-10-04 and v4.0.4 on 2026-10-15, and the last push was on 2026-10-19 with the repository not archived. That cadence is what makes the absence of an official API tolerable for most uses, since the community patches what Yahoo breaks. The README also points at related projects, among them Ghostfolio, an MCP server for real time financial data, a Cloudflare Workers demo, and an open source portfolio tracker, which is a reasonable way to judge the project's health without relying on any number of users.

## Conclusion

yahoo-finance2 fits a Node or edge project that needs quotes, fundamentals, charts and options without a paid market data feed, and it fits an agent workflow through the MCP tools and the packaged skill, which is a rare combination for a finance client. It is the wrong choice for a product that needs a supported data source, since the project states plainly that it is neither created nor endorsed by Yahoo and that no guarantees are made about service availability or API consistency, and it is a poor fit if you depend on historical data for tickers that may be delisted, because that data disappears from Yahoo's side. Before you adopt it, read the error handling notes, run the CLI against a symbol you will need historically, and confirm that your deployment target is one of the listed runtimes, since the browser is explicitly ruled out.

## FAQ

### How do I use yahoo-finance2 from the command line?

Run npx yahoo-finance2 --help, then pass a command such as search AMZN or quoteSummary GOOGL, adding a modules array as JSON to request specific sections. For a global install, use npm install -g yahoo-finance2 and then the shorter yahoo-finance command, which also accepts an options object as its last argument.

### Can yahoo-finance2 run in the browser?

No, because of CORS and cookie issues. The README says to run the calls on a server or in a serverless or edge function and pass the data to the browser, using React Server Components, trpc or other strategies to keep the types intact.

### What happens to the data of a stock that gets delisted?

Yahoo removes all related data, including historical and chart data from periods before the delisting. Queries that worked before will start failing, and the README states there is no way to retrieve that data again, so anything you need to keep should be copied.

## Sources

- [gadicc/yahoo-finance2 on GitHub](https://github.com/gadicc/yahoo-finance2)
- [License: MIT](https://github.com/gadicc/yahoo-finance2/blob/dev/LICENSE)
- [Project website](https://www.npmjs.com/package/yahoo-finance2)
- [README](https://github.com/gadicc/yahoo-finance2/blob/dev/README.md)
- [Releases](https://github.com/gadicc/yahoo-finance2/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/gadicc-yahoo-finance2