yahoo-finance-mcp

# <img src="https://raw.githubusercontent.com/benethos-hub/yahoo-finance-mcp/main/assets/icon.svg" alt="" width="40" height="40"> Unofficial Yahoo Finance MCP Server

[![CI](https://github.com/benethos-hub/yahoo-finance-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/benethos-hub/yahoo-finance-mcp/actions/workflows/ci.yml)
[![PyPI benethos-yahoo-finance-mcp](https://img.shields.io/pypi/v/benethos-yahoo-finance-mcp?label=PyPI%20benethos-yahoo-finance-mcp)](https://pypi.org/project/benethos-yahoo-finance-mcp/)
[![Container benethos-yahoo-finance-mcp](https://img.shields.io/badge/ghcr.io-benethos--yahoo--finance--mcp-2496ED?logo=docker&logoColor=white)](https://github.com/benethos-hub/yahoo-finance-mcp/pkgs/container/benethos-yahoo-finance-mcp)
[![Python](https://img.shields.io/pypi/pyversions/benethos-yahoo-finance-mcp)](https://pypi.org/project/benethos-yahoo-finance-mcp/)
[![Coverage](https://img.shields.io/badge/coverage-97%25-brightgreen)](https://github.com/benethos-hub/yahoo-finance-mcp/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/license-MIT-blue)](https://github.com/benethos-hub/yahoo-finance-mcp/blob/main/LICENSE)

<!-- The MCP Registry looks for this line in the README on PyPI to accept the package as the one in server.json. -->
<!-- mcp-name: io.github.benethos-hub/benethos-yahoo-finance-mcp -->

An [MCP](https://modelcontextprotocol.io) server that exposes Yahoo Finance
data to MCP clients (such as Claude Desktop). It runs over **stdio** (default,
for local clients) or an **HTTP** transport (for standalone / containerized
hosting). Market data is sourced through the
[`yfinance`](https://github.com/ranaroussi/yfinance) library, which uses
Yahoo's unofficial endpoints.

> **Disclaimer**
>
> - This project is **not affiliated with, endorsed by, or sponsored by Yahoo**.
>   "Yahoo" and "Yahoo Finance" are trademarks of their respective owners.
> - It relies on **unofficial** Yahoo Finance endpoints via `yfinance`. Those
>   endpoints can change or break at any time, and Yahoo may rate limit or block
>   requests. Review Yahoo's Terms of Service before use.
> - Data may be delayed, incomplete, or inaccurate. **Nothing here is financial
>   advice.** Do not rely on it for trading or investment decisions.
> - Provided "as is", without warranty. Intended for personal and educational
>   use. You use it at your own risk. See [LICENSE](https://github.com/benethos-hub/yahoo-finance-mcp/blob/main/LICENSE).
> - For **commercial use**, review Yahoo's Terms of Service and consider a
>   properly licensed market-data provider instead of the unofficial endpoints.

**Contents**

- [What it is for](#what-it-is-for) · [Example prompts](#example-prompts)
- [Tools](#tools) · [Symbol resolution](#symbol-resolution)
- [Compatible clients](#compatible-clients) · [Requirements](#requirements)
- [Installation](#installation)
  - [Quick start: Claude Desktop extension](#quick-start-claude-desktop-extension)
  - [Claude Desktop with uv (manual config)](#claude-desktop-with-uv-manual-config)
  - [Other ways to install](#other-ways-to-install)
- [Running as a standalone server](#running-as-a-standalone-server):
  [Docker](#docker), [Docker Compose](#docker-compose),
  [Manual (uv or venv)](#manual-uv-or-venv)
- [Caching](#caching) · [Development](#development) · [Trademarks](#trademarks)

## What it is for

The server lets an MCP client such as Claude Desktop answer questions about
markets from live Yahoo Finance data: the price of a share and how it moved,
what a company earns, what analysts expect, who owns it, what an ETF holds,
and how a sector or a market is doing. You ask in plain language, the client
picks the tools, and the answer rests on what Yahoo returns rather than on
what the model remembers.

<img src="https://raw.githubusercontent.com/benethos-hub/yahoo-finance-mcp/main/assets/architecture.png" alt="How a question gets answered: you ask an MCP client such as Claude, it calls a tool of this server, the server fetches from Yahoo Finance via yfinance, and the answer goes back the same way" width="100%">

Typical uses:

- **Quick lookups in a chat.** A quote, the 52-week range, the next earnings
  date or the dividend history, without opening a browser.
- **Research on one company.** Profile, financial statements, estimates,
  rating changes, holders and insider trades in one conversation, summarised
  by the model.
- **Comparisons.** Several tickers side by side, the top companies of a sector
  or an industry, the holdings and weightings of an ETF.
- **Calculations on raw data.** Six months of daily closes for an RSI, a MACD
  or a drawdown, which the model works out from the series.
- **A shared service.** Run over HTTP, in Docker, for a team's web front end or
  an automation such as n8n, with an optional result cache in front of Yahoo.

Everything is read-only. The server places no orders, holds no portfolio and
signs in nowhere. The data comes from unofficial endpoints, may be delayed and
is no basis for a trading decision, see the disclaimer above.

### Example prompts

Once the server is connected, ask the client in plain language and it will pick
the tools. Replace the bracketed placeholders with concrete values.

**Price & quote**

- "What's the current price of [Ticker], and how far is it from its 52-week high?"
- "Is [Ticker] trading above or below its 50- and 200-day moving averages?"
- "Get the daily closes of [Ticker] for the last 6 months and compute RSI and MACD."
- "What was the deepest drawdown of [Ticker] in the last 12 months?"
- "Compare [Ticker A] and [Ticker B] over the last 3 months and show which held up better."
- "Get current quotes for [Ticker A], [Ticker B] and [Ticker C] and compare them in a table."

**Company & valuation**

- "Give me P/E, beta, market cap and dividend yield for [Ticker]."
- "What does [Company name] actually do, and which sector and industry is it in?"
- "Show the last three annual income statements for [Ticker] and how revenue developed."
- "How has [Ticker]'s share count changed over the past years, and does that mean buybacks or dilution?"

**Analysts & news**

- "What's the analyst consensus for [Ticker], and how far is the average price target from the current price?"
- "Any upgrades or downgrades for [Ticker] in the last few weeks?"
- "What are the forward revenue and EPS estimates for [Ticker], and how were they revised recently?"
- "Summarize the recent news on [Ticker]."

**Earnings & calendar**

- "When does [Ticker] report next, and what EPS is expected?"
- "How did [Ticker] do against estimates in the last few quarters?"
- "When are [Ticker]'s next earnings and ex-dividend dates?"

**Dividends**

- "Show [Ticker]'s dividends over the last ten years and the current yield."
- "Has [Ticker] cut its dividend in the last 20 years, and did it split the stock?"

**Ownership & insiders**

- "Who are the largest institutional holders of [Ticker]?"
- "What share of [Ticker] is held by insiders versus institutions?"
- "Has there been notable insider buying or selling in [Ticker] recently?"

**Funds & ETFs**

- "What are the top holdings and sector weightings of the ETF [Ticker]?"
- "What's the asset-class split of [ETF Ticker], and which fund family runs it?"

**Filings**

- "Show the most recent SEC filings for [US Ticker] with links."

**Options**

- "Which option expiration dates are available for [US Ticker]?"
- "Show the calls and puts for [US Ticker] expiring [Date]."

**Sectors & markets**

- "What are the top companies and industries in the technology sector?"
- "Show the top-performing companies in the semiconductors industry."
- "Is the US market open right now, and when does it open next?"
- "How did the major indices in Europe and Asia close?"

**Screening**

- "Find US stocks with a dividend yield above 4 % and a P/E below 15."
- "Which companies have raised their dividend for at least 25 years in a row?"
- "List the largest German-listed technology stocks with a positive P/E under 20."

**Finding a symbol**

- "Which Yahoo ticker belongs to [Company name] on [Exchange]?"
- "Resolve the ISIN [ISIN] to a Yahoo ticker."

**A daily round-up**

- "For [Ticker A], [Ticker B] and [Ticker C]: pull quote, six months of history,
  company info and analyst recommendations, then give me a short picture of each."

> **The server computes nothing itself.** It passes through what Yahoo returns,
> which already includes derived figures such as moving averages, P/E, beta and
> dividend yield. Anything Yahoo does not carry — RSI, MACD, drawdown,
> sentiment, total return — the model works out from the raw series.

## Tools

Every tool only reads, and each one says so to the client with the MCP
annotations `readOnlyHint` and `openWorldHint`. A client that honours them may
run the tools without asking for confirmation each time. Each tool also has a
short title, such as "Stock screener", that a client may show in place of its
name.

| Tool | Description |
|------|-------------|
| `search` | Find instruments by name, ticker, or ISIN, returning Yahoo symbols. |
| `get_quote` | Current price and key intraday figures for a symbol. |
| `get_quotes` | Compact current quotes for several symbols at once (per-symbol not-found list). |
| `get_history` | Historical OHLCV data (period/interval or explicit date range). |
| `get_company_info` | Company profile and key statistics (sector, market cap, P/E, …). |
| `get_financials` | Income statement, balance sheet, or cash flow (annual/quarterly/ttm). |
| `get_dividends` | Dividend and stock-split history. |
| `get_news` | Recent news headlines (title, summary, publisher, URL), up to the 10 Yahoo serves. |
| `get_recommendations` | Analyst recommendation trend and price targets. |
| `get_options` | Option expiration dates and the calls/puts chain for a date, centred on the money. |
| `get_earnings` | Upcoming and historical earnings (EPS estimate/actual, surprise). |
| `get_estimates` | Forward analyst est