# finance-mcp

> Real-time stock & crypto market data for LLMs, over the [Model Context Protocol](https://modelcontextprotocol.io).

[![CI](https://github.com/porkornrawee/finance-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/porkornrawee/finance-mcp/actions/workflows/ci.yml)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-261230)](https://github.com/astral-sh/ruff)

`finance-mcp` is an MCP server that lets any MCP-compatible client (Claude Desktop,
Cline, Continue, …) pull live equity and crypto quotes, historical candles, and
common technical indicators — so the model can reason over real market data instead
of hallucinating it.

```
┌──────────────┐   MCP (stdio)   ┌───────────────┐   HTTP   ┌──────────────┐
│  LLM client  │ ◀─────────────▶ │  finance-mcp  │ ◀──────▶ │  yfinance    │
│ (Claude etc.)│   tool calls    │    server     │          │  CoinGecko   │
└──────────────┘                 └───────────────┘          └──────────────┘
```

## Demo

![finance-mcp demo](docs/demo.gif)

> The session above is illustrative; the JSON matches the real shape returned by
> `compare_assets`. Regenerate it any time with `python scripts/make_demo.py`.

## Features

- **`get_stock_quote`** — latest price, day change, % change for any ticker (`AAPL`, `SPY`, …)
- **`get_quotes`** — batch quotes for many tickers, fetched concurrently
- **`get_stock_history`** — OHLCV candles over a configurable period/interval
- **`get_crypto_price`** — live crypto quotes via CoinGecko (no API key needed)
- **`analyze_stock`** — SMA(20/50), EMA(20), and RSI(14) computed in-process
- **`compare_assets`** — rank a mix of stocks and crypto by their % move
- Provider layer isolates each upstream API behind a small, **fully unit-tested** surface
- Async throughout; blocking provider I/O is offloaded to worker threads

## Install

```bash
git clone https://github.com/porkornrawee/finance-mcp.git
cd finance-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
```

## Use with Claude Desktop

Add this to your `claude_desktop_config.json` (see [`examples/`](examples/)):

```json
{
  "mcpServers": {
    "finance": {
      "command": "finance-mcp",
      "args": []
    }
  }
}
```

Restart Claude Desktop, then ask things like:

> "What's the RSI on NVDA over the last 6 months, and how does it compare to Bitcoin's 24h move?"

## Tools

| Tool | Arguments | Returns |
| --- | --- | --- |
| `get_stock_quote` | `symbol` | price, change, %, currency |
| `get_quotes` | `symbols` | list of quotes (per-symbol errors isolated) |
| `get_stock_history` | `symbol`, `period`, `interval` | list of OHLCV candles |
| `get_crypto_price` | `coin_id`, `vs_currency` | price, 24h change |
| `analyze_stock` | `symbol`, `period` | latest close + SMA/EMA/RSI |
| `compare_assets` | `stocks`, `crypto`, `vs_currency` | assets ranked by % move + best/worst |

> **Note:** crypto uses CoinGecko *ids* (the slug), e.g. `bitcoin`, not `BTC`.

## Development

```bash
ruff check .     # lint
mypy src         # type-check
pytest -q        # tests (network-free; CoinGecko is mocked with respx)
```

The indicator math in [`indicators.py`](src/finance_mcp/indicators.py) is intentionally
pure and dependency-free so it can be tested deterministically without hitting any API.

## Disclaimer

This project is for informational and educational purposes only. It is **not** financial
advice. Market data is provided by third parties on a best-effort basis and may be
delayed or inaccurate.

## License

MIT © porkornrawee — see [LICENSE](LICENSE).