# yfinance-mcp

[![ci](https://github.com/saksham10arora-dotcom/yfinance-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/saksham10arora-dotcom/yfinance-mcp/actions/workflows/ci.yml)
![python](https://img.shields.io/badge/python-3.10%2B-blue)
![license](https://img.shields.io/badge/license-MIT-green)
![protocol](https://img.shields.io/badge/Model_Context_Protocol-violet)

**Live market data for your AI.** A [Model Context Protocol](https://modelcontextprotocol.io) server that gives Claude (or any MCP client) real-time quotes, OHLCV history, full options chains, news, and multi-ticker comparison. Free, no API key.

<div align="center">
  <img src="assets/demo.svg" alt="Claude answering a market question through yfinance-mcp" width="860">
</div>

## Why

LLMs answer market questions with training-data guesses. Wire this server in once and they stop guessing:

- *"What's Apple trading at?"* → live quote instead of a stale hallucination
- *"Pull AAPL options expiring next month"* → real strikes with IV and open interest
- *"NVDA vs AMD vs INTC this year?"* → actual returns, volatility, drawdowns, computed from data
- *"Any recent news on PLTR?"* → headlines with links it can cite

## Tools

| Tool | What it does | Example prompt |
|---|---|---|
| `get_quote` | Last price, day range, volume, market cap, 52w range, change % | "what's TSLA doing today?" |
| `get_history` | OHLCV bars (any period × interval) + summary stats | "SPY daily closes for 2024" |
| `get_options_chain` | Calls & puts: strike, last, bid/ask, IV, OI, volume, ITM | "AAPL chain for next month" |
| `get_news` | Recent headlines with links | "any news on PLTR?" |
| `compare_tickers` | Return, annualized vol, max drawdown side by side; names the winner | "MSFT vs GOOGL, 3 months" |

Responses are JSON, truncated to LLM-friendly sizes (history capped at 250 bars, options at 60 rows/side), with summary statistics so the model reasons over aggregates before raw bars.

## Setup

```bash
git clone https://github.com/saksham10arora-dotcom/yfinance-mcp
cd yfinance-mcp
python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
```

### Claude Desktop / any MCP client

Add to `claude_desktop_config.json` (File → Settings → Developer → Edit Config):

```json
{
  "mcpServers": {
    "yfinance": {
      "command": "/absolute/path/to/yfinance-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/yfinance-mcp/server.py"]
    }
  }
}
```

Restart Claude Desktop. The tools appear under the 🔨 icon. Ask about any ticker.

### Verify without an MCP client

```bash
./.venv/bin/python -c "import server; print(server.get_quote('AAPL'))"
```

CI runs the same stdio handshake GitHub does on every push, so `main` is always protocol-correct.

## FAQ

**Is data real-time?**
Yahoo Finance data: near-real-time for US equities, delayed for some international exchanges. Good for research and chat, not for order execution.

**Does it cost anything?**
No. No API key, no rate-limit account, nothing to configure.

**Why not just paste yfinance code into chat?**
You can. This removes the copy-paste loop and lets the model decide *which* tool to call per question, including multi-step ones ("compare these five tickers, then pull the chain on the most volatile").

**Windows?**
Works. Point the config at `.venv\Scripts\python.exe` and use double backslashes in JSON.

## Troubleshooting

- **Tool icon missing after restart**: paths in the config must be absolute; relative paths silently fail.
- **`no data for <ticker>`**: delisted or misspelled symbol; check Yahoo Finance in a browser.
- **Rate limiting after heavy use**: back off a few minutes; Yahoo throttles bursts.

## Alternatives compared

| | yfinance-mcp | Paid market MCPs |
|---|---|---|
| API key | none | required |
| Cost | free | $10-100+/mo |
| Options chains with IV | yes | varies |
| Real-time depth/L2 | no | sometimes |
| Setup time | 2 min | account + billing |

## License

MIT. Not investment advice; the AI reading your portfolio is not a fiduciary.