MCP Yahoo Finance

MCP Yahoo Finance is a Model Context Protocol (MCP) server. It gets data from Yahoo Finance. You can use it to get stock prices, company data, past prices, financial reports, news, analyst ratings, earnings dates, dividends, and options data.

This project is in early development. Tool names and response fields can change between releases.

Install

You can run mcp-yahoo-finance without a separate install. Use uvx.

Use pip

pip install mcp-yahoo-finance

Use Git

Clone the repository. Then install the development environment:

git clone git@github.com:maxscheijen/mcp-yahoo-finance.git
cd mcp-yahoo-finance
uv sync

Configure

Claude Desktop

Add this entry to your claude_desktop_config.json file:

{
    "mcpServers": {
        "yahoo-finance": {
            "command": "uvx",
            "args": ["mcp-yahoo-finance"]
        }
    }
}

You can also use Docker. Replace IMAGE with the Docker image name:

{
    "mcpServers": {
        "yahoo-finance": {
            "command": "docker",
            "args": ["run", "-i", "--rm", "IMAGE"]
        }
    }
}

VS Code

Add this entry to your .vscode/mcp.json file:

{
    "servers": {
        "yahoo-finance": {
            "command": "uvx",
            "args": ["mcp-yahoo-finance"]
        }
    }
}

Example questions

You can ask questions like these:

1. "What is the stock price of Apple?"
2. "Give me a rich quote for AAPL with the previous close, intraday range, and market status."
3. "Show me the company overview for Nvidia."
4. "What is the difference in stock price between Apple and Google?"
5. "How much did the stock price of Apple change between 2024-01-01 and 2025-01-01?"
6. "What are the available options expiration dates for AAPL?"
7. "Show me the options chain for AAPL expiring on 2024-01-19."
8. "What are the call and put options for Tesla?"

Response data

Tools return data in JSON format. This is an example of a rich quote:

{
  "symbol": "AAPL",
  "currentPrice": 243.5822,
  "previousClose": 241.33,
  "absoluteChange": 2.2522,
  "percentChange": 0.9331,
  "open": 242.1,
  "dayHigh": 244.2,
  "dayLow": 241.9,
  "volume": 45678901,
  "marketStatus": "REGULAR",
  "currency": "USD",
  "exchange": "NMS",
  "timestamp": "2025-01-02T15:30:00+00:00",
  "source": {
    "provider": "Yahoo Finance",
    "endpoint": "info",
    "fetchedAt": "2025-01-02T15:30:01+00:00"
  }
}

Errors use the same format for all tools. An error includes an error code and a message:

{
  "error": {
    "code": "NO_DATA",
    "message": "No historical data found for AAPL"
  }
}

Historical and table results keep the column names from the data source. Dates use the YYYY-MM-DD format. The server does not show the time zone used by Yahoo Finance.

Historical price tools return adjusted prices by default. Adjusted prices include changes from stock splits and dividends. To get prices without these changes, set adjusted to false in get_historical_stock_prices.

Date searches include both the start date and the end date. If a date is a weekend or market holiday, there may be no price data for that date. In that case, the tool returns a NO_DATA error.

If quote or company data is missing, its value is null. The news tool returns 10 articles by default. It can return up to 100 articles. It includes the title, URL, publisher, thumbnail, related stock symbols, and publish time. The publish time uses UTC and the ISO 8601 format. You can set start_date and end_date to filter news. The filter includes both dates.

Recommendation, earnings, dividend, financial report, and options tools use a top-level symbol field. They return data from Yahoo Finance when that data is available.

Available tools

Use Yahoo Finance ticker symbols for symbol values. Examples are AAPL and MSFT.

Performance calculations

Performance analysis uses closing prices adjusted for stock splits and dividends.

Total return is (last close / first close) - 1.

Annual volatility is the standard deviation of daily returns multiplied by sqrt(252).

Maximum drawdown is the largest fall from a previous high.

The tool calculates correlation from daily returns on dates shared by the symbols. This lets it compare symbols that have different trading calendars.

Develop locally

Run uv sync to install the locked development environment. Then run these commands:

uv run pytest
uv run ruff check .
uv run ruff format --check .
uv build

You can also use these Makefile commands:

make test
make lint
make docker-build

The tests use mock Yahoo Finance data. They do not make live requests to Yahoo Finance.

Build the Docker image

Run this command:

docker build -t mcp-yahoo-finance .

Test with MCP Inspector

Run this command:

npx @modelcontextprotocol/inspector uv run mcp-yahoo-finance

Yahoo Finance limits

Yahoo Finance is a third-party data source. Its data can be late, incomplete, or unavailable. This project does not give investment advice. It does not guarantee that the data is correct, complete, or up to date. Check important data with an authoritative source before you use it.