# trade-analytics-mcp

**Give your AI eyes and a ruler for your trades.** An open-source MCP server that lets your
LLM/agent pull the real price action around every fill in an order-history export, *see* each trade
on a candlestick chart, and *measure* it — heat taken, R-multiple, whether it went green before red,
how much of the move it captured — so it can tell you whether a loss was **bad luck or bad location**.

You bring your own market-data key; the data stays on your machine.

---

## Why — what it actually lets your AI do

An order-history export (Tradovate, your broker's CSV, …) is just timestamps, prices, sizes, sides.
From that alone an AI can spot *behaviour* — overtrading, revenge entries, size creep, bad
time-of-day — but it is **blind to trade-location quality**: was the entry into structure or a chase?
how much adverse excursion did you sit through? did you cut a winner early? was the stop sane for the
volatility?

This MCP closes that gap — in two tiers.

### 🆓 Free, on your machine

`resolve_symbol` + `get_price_context` run **100% locally** under your own Databento key — no
account, no fee, no data leaving the machine. Your agent can:

- turn *"MNQ" / "micro nasdaq"* into the exact contract, point value, and front-month; and
- pull the **real OHLCV around each fill** (auto-windowed) with your entries/exits/stops as **JSON**,

so it reasons over the *actual* price path — where the entry sat, the shape of the move, proximity to
the day's high/low — instead of guessing. That alone turns *"I think I chased"* into a grounded read.

### 💳 With a trade-analytics API key (free tier — no card)

`render` and `analyze` send only the **numeric slice** of that same local data to the hosted API and
add the two things that are tedious or impossible to do well from raw JSON. The API has a **free
tier (no credit card)**, so you can try the full experience at no cost — paid tiers only raise the
monthly quota:

- **`render`** — an annotated **candlestick chart image** (entries ▲ / exits ▼, SL/TP zones, reference
  levels), returned *and saved to a file* so your AI can drop it into a journal.
- **`analyze`** — the precise per-trade metrics that separate *good-trade-bad-outcome* from
  *bad-location*: **MAE / MFE** (heat vs best excursion), **R-multiple**, **went-green-first**,
  **capture efficiency**, plus USD P&L, time-in-trade, win rate, and session roll-ups.

So — with the paid tools — instead of *"you lost on trade #3,"* your AI can say:

> *"Trade #3 (short at 20,110) went +0.8R in your favour within three minutes, then reversed through
> your entry to −18 pts before you exited at −15 — MFE 12, MAE 18, capture −1.2. Location was fine
> (into the prior-day high); **management wasn't**,"* — and hand you the annotated chart.

### A typical review

> **"Review my MNQ trades from last week."** → your agent reconstructs the round-trips, calls
> `resolve_symbol` (MNQ → the right contract), `analyze` (per-trade MAE/MFE/R/capture + a session
> summary), and `render` on the notable trades (charts saved to your vault), then writes the review
> with the numbers *and* the pictures.

---

## Tools

| Tool | What it does | Cost |
|---|---|---|
| `resolve_symbol` | "MNQ" / "micro nasdaq" → precise contract, point value, front-month | **Free**, local |
| `get_price_context` | OHLCV + your entries/exits/SL as **JSON** for a window auto-sized around the trade | **Free**, local |
| `render` | An annotated **candlestick chart image**, returned *and saved to a file* (PNG or SVG) | Paid |
| `analyze` | Per-trade **MAE/MFE, R-multiple, went-green-first, capture efficiency** + summary | Paid |

`resolve_symbol` and `get_price_context` run **100% on your machine** under your own data key — no
account, no fee. `render` and `analyze` forward only the **numeric slice** of your own data to the
hosted [trade-analytics API](https://trade-context.mcp.o-gw.com) and return the result; nothing is retained.

---

## Setup

### 1. Get a Databento key (your market data)

[Databento](https://databento.com) is a modern market-data provider — institutional-grade historical
and live data through a simple API. This example MCP implementation uses it to fetch the candles
around your trades, under **your own** key, locally.

- **No subscription.** It's **pay-as-you-go**, and new accounts get a **free usage credit** that
  comfortably covers normal trade review — historical 1-minute OHLCV is cheap and is often effectively
  free within that credit.
- Sign up at **[databento.com](https://databento.com)** → open the portal → **create an API key** →
  that's your `DATABENTO_API_KEY`.

Your key and your data stay on your machine; only the numeric slices you `render`/`analyze` leave it.

### 2. Get a trade-analytics API key — free to start

`render` and `analyze` call the hosted API, which has a **free tier (no credit card)** — so you can
use the full experience right away; paid tiers only raise the monthly quota.

1. Open the **[dashboard](https://trade-context.mcp.o-gw.com/dashboard)** and **sign up** (free).
2. Click **Create key** and copy it — it's shown **once** (looks like `tc_live_…`).
3. Add it to your MCP config as `TRADE_ANALYTICS_API_KEY` (step 3 below).

> **You don't need this to get started.** The MCP connects and the **free local tools work with just
> your Databento key** — the API key only unlocks `render` + `analyze`, so add it whenever you want
> charts or analysis. Call those without a key and you'll get a friendly "grab a key" message, not a
> crash.

### 3. Add the MCP to your client

**Claude Code** (or any terminal harness):

```bash
claude mcp add trade-analytics \
  -e DATABENTO_API_KEY=db-your-key \
  -e TRADE_ANALYTICS_API_KEY=tc_live_your-key \
  -- npx -y trade-analytics-mcp
```

Drop the `TRADE_ANALYTICS_API_KEY` line to run just the free local tools.

**Claude Desktop / other MCP clients** — add to the config:

```json
{
  "mcpServers": {
    "trade-analytics": {
      "command": "npx",
      "args": ["-y", "trade-analytics-mcp"],
      "env": {
        "DATABENTO_API_KEY": "db-your-key",
        "TRADE_ANALYTICS_API_KEY": "tc_live_your-key"
      }
    }
  }
}
```

### Configuration

Resolved with precedence **CLI flags > env > defaults**:

| Setting | Env | Flag | Notes |
|---|---|---|---|
| Databento key | `DATABENTO_API_KEY` | `--databento-key` | Required. Your own; data stays local. |
| API key | `TRADE_ANALYTICS_API_KEY` | `--api-key` | Only for `render` / `analyze`. |
| API URL | `TRADE_ANALYTICS_API_URL` | `--api-url` | Defaults to the hosted API. |
| Output dir | `TRADE_ANALYTICS_OUTPUT_DIR` | `--output-dir` | Where `render` saves images. |

---

## Built on the trade-analytics API

This whole server is a **thin client** — it fetches data locally and calls the
**[trade-analytics API](https://trade-context.mcp.o-gw.com)** for the rendering and analysis. That API
is a general, data-agnostic service for **turning OHLC data into chart images and trade metrics**:
send it candles (from *any* source), get back a chart or a trade analysis. This MCP is just one
example of what you can build on it — a dashboard, a trading bot, a Discord/Slack integration, a
backtest reporter, or your own journaling tool would all sit on the same endpoints.

## Privacy

- Your Databento key and your market data live **on your machine**.
- The free tools make **no network calls** to us at all.
- `render` / `analyze` send only the **numeric candle slice** needed for that one call; the API is
  **stateless and retains nothing**.

## Develop

```bash
npm install
npm run typecheck && npm test && npm run build
npm run dev   # run the stdio server locally
```

MIT licensed. Issues and PRs welcome.