# mcp-stock-server (FinanceExpert)

A small [Model Context Protocol](https://modelcontextprotocol.io/) server built with **FastMCP**. It exposes Yahoo Finance market data (via **yfinance**) so assistants can fetch quotes, history as CSV, and **plain-text Unicode price charts**.

## Requirements

- Python **3.11+**
- [uv](https://docs.astral.sh/uv/) (recommended) or another way to install dependencies from `pyproject.toml`

## Setup

```bash
cd mcp-stock-server
uv sync
```

## Run (stdio)

The server speaks MCP over stdio (the default for `mcp.run()`):

```bash
uv run python server.py
```

## Add as an MCP server (Cursor)

1. Open **Cursor Settings → MCP** (or edit your MCP JSON config — often **`~/.cursor/mcp.json`** on macOS/Linux).
2. Register a **stdio** server whose working directory is this repo and whose command starts `server.py`.

### Option A — `uv run` (recommended)

Replace **`/absolute/path/to/mcp-stock-server`** with the real path where you cloned the repo.

```json
{
  "mcpServers": {
    "FinanceExpert": {
      "command": "uv",
      "args": ["run", "python", "server.py"],
      "cwd": "/absolute/path/to/mcp-stock-server"
    }
  }
}
```

After `uv sync`, this uses the locked dependencies from **`uv.lock`**.

### Option B — project virtualenv Python

Use this if you prefer not to invoke `uv` from the MCP client:

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

Create the venv first (from the repo root): **`uv sync`** (installs deps into `.venv`).

3. **Save** the config and **restart Cursor** (or reload MCP). In the MCP panel you should see **FinanceExpert** with tools **`get_stock_analysis`**, **`get_historical_prices`**, and **`get_stock_price_chart`**.

Other MCP clients (e.g. Claude Code, editors with MCP support) use the same idea: **`command`** + **`args`** + **`cwd`** for a stdio server.

## Tools

| Tool | Description |
|------|-------------|
| `get_stock_analysis` | Snapshot text: current price, 50-day average, analyst recommendation key (from `Ticker.info`). |
| `get_historical_prices` | Daily **close** column as CSV for a lookback of **`days`** calendar days (`period=f"{days}d"`). Default `days=30`. |
| `get_stock_price_chart` | Box-drawn **ASCII/Unicode chart**: area fill, price axis, start/end dates on the time axis, and an 8-step sparkline. |

### `get_stock_price_chart` parameters

- **`ticker`** — Symbol, e.g. `INTU`, `AAPL`.
- **`days`** — Used when **`period`** is omitted: Yahoo range `Nd` (calendar days). Default **30**.
- **`period`** — Optional Yahoo period string; when set, it overrides **`days`**. Examples: **`10y`**, **`5y`**, **`1y`**, **`6mo`**, **`ytd`**, **`max`**.

Examples:

- Last month of sessions (by calendar days): `days=30`
- Last ten calendar years (Yahoo window): `period="10y"`

Market data comes from Yahoo through yfinance; semantics match [yfinance `history(period=...)`](https://github.com/ranaroussi/yfinance).

## Disclaimer

Quotes and history are **informational only**, not investment advice. Yahoo data can lag or contain errors; verify independently for decisions.