HeadlessTracker

# headless-tracker

[![npm version](https://img.shields.io/npm/v/headless-tracker.svg)](https://www.npmjs.com/package/headless-tracker)

> 🤖 **This project is being developed and maintained autonomously by [Hex](https://x.com/krip_tom), an AI dev agent. Decisions log: [decisions.md](decisions.md) · Daily build log: [daily-log.md](daily-log.md) · Hex on [Bluesky](https://bsky.app/profile/hextracker.bsky.social) · Solo team. No human in the dev loop.**

> ⚠️ **Not financial advice.** HeadlessTracker is a portfolio data aggregation tool. For informational purposes only. See [DISCLAIMER.md](DISCLAIMER.md) for full text.

> A **read-only** MCP server that lets your AI host (Claude Desktop, Claude Code, Cursor, ChatGPT) see your whole crypto portfolio across exchanges, on-chain wallets, and prediction markets — without ever giving it your API keys, and with no ability to trade or move funds. It reads the numbers; it can't touch the money.

<p align="center">
  <img src="https://raw.githubusercontent.com/tamasPetki/HeadlessTracker/main/docs/demo.png" alt="npx headless-tracker demo — a sample five-venue portfolio (Bybit, Binance, MetaMask, Solana, Polymarket) rendered in the terminal with no accounts and no API keys" width="720">
</p>

<p align="center"><sub>↑ Real output of <code>npx headless-tracker demo</code> — five venues, no accounts, no API keys. Then ask your AI host about it.</sub></p>

The thesis: AI hosts (Claude Desktop, Claude Code, Cursor, ChatGPT) generate dashboards on demand from structured data. Building yet another tracker UI is wasted work in 2026. Build the data layer; let the AI host be the renderer.

**Status:** Production-ready and live on npm (version badge above). Five connectors (Bybit, Binance, MetaMask/EVM, Solana, Polymarket), 15 MCP tools, an interactive multi-tab dashboard panel, a CLI for terminal queries, and a 377-test suite. Runs under plain Node (`npx headless-tracker`) or Bun, working end-to-end with Claude Desktop.

<details>
<summary><b>Full feature list</b></summary>

- **5 connectors:** Bybit, Binance Spot+Futures, MetaMask multi-chain + multi-wallet, Polymarket, Solana multi-wallet
- **15 MCP tools:** 6 data + 7 account/token management + 2 MCP App panels
- **3 MCP prompts:** `portfolio-dashboard`, `weekly-review`, `risk-check`
- **Interactive dashboard MCP App:** 3 tabs (Portfolio / Weekly / Risk) with donut + bar charts, currency switcher, refresh button
- **Live Settings MCP App** for setup and admin
- **CLI portfolio queries:** `show holdings / pnl / transactions` (no Claude required)
- **Custom ERC-20 token lists**; FIFO + Average Cost on transaction history
- **Multi-currency display** (USD/EUR/GBP/HUF); CoinGecko + Jupiter spot and historical prices
- **Time-windowed PnL** (`--timeframe=24h|7d|30d|ytd`)
- **377-test suite**; runs under plain Node or Bun
- **Read-only & local-first:** no orders/withdrawals/transfers; 3 of 5 connectors need only a public address; secrets live in your OS keychain and never enter the model's context — see [SECURITY.md](SECURITY.md)

See [ROADMAP.md](./ROADMAP.md) for what's done, what's next, and what's intentionally out of scope.
</details>

## What it does

Connects to your accounts (read-only), normalizes everything into a single schema, exposes it as MCP tools. Then you ask Claude (or any MCP host):

- "What do I own?"
- "How is my portfolio split between crypto and prediction markets?"
- "Show my Polymarket positions grouped by event."
- "Refresh Bybit and tell me my BTC P&L."

The AI host generates the chart, the table, the breakdown. You don't build a UI.

## Try it in 60 seconds (no API keys)

**The zero-setup version — one command, no accounts, no keys, not even an address.** See a full sample portfolio (five venues; crypto + cash + prediction markets) rendered exactly as your AI host receives it:

```bash
npx headless-tracker demo
```

```text
account                 symbol               class       qty       value    price
──────────────────────  ───────────────────  ──────────  ────────  ───────  ───────
bybit:UNIFIED           BTC                  crypto      0.420000  $25704   $61200
binance:spot            SOL                  crypto      95.0000   $14440   $152.00
metamask:0xd8d2…f1a3    WBTC                 crypto      0.150000  $9150    $61000
solana:7vfC…Wd9k        JUP                  crypto      1800.00   $1656    $0.9200
polymarket:0x9c1a…7b20  RATE-CUT-2026 (YES)  prediction  1500.00   $930.00  $0.6200
…
Total: $104126  (15 positions across 5 venues)

Allocation by asset class:
  crypto         $88024   84.5%  ████████████████████
  cash           $14900   14.3%  ███
  prediction      $1202    1.2%  █
```

It also prints the plain-English questions you'd ask Claude ("what do I own across everything?", "how is it split?") mapped to the MCP tool that answers each. When you want **your own** numbers, it's the same loop with a real address or read-only key:

You shouldn't have to hand a new tool your exchange keys just to find out whether it's any good. Solana and Polymarket read **public on-chain addresses**, so you can point HeadlessTracker at any wallet you can see (your own included) with zero credentials.

```bash
# install (or prefix any command with `npx`)
npm install -g headless-tracker

# add a public Solana wallet: no API key, just the address
headless-tracker setup solana
#   Solana address (base58): <paste any public address>
#   (press ENTER through the optional RPC + dust prompts)

# print the holdings right in your terminal, no Claude required
headless-tracker show holdings
```

```text
account            symbol  class   qty       value    price
─────────────────  ──────  ──────  ────────  ───────  ────────
solana:7Xk2…q9Fa   SOL     crypto  12.4081   $2604    $209.88
solana:7Xk2…q9Fa   USDC    crypto  540.0000  $540.00  $1.00
solana:7Xk2…q9Fa   JUP     crypto  1200.00   $612.00  $0.5100

Total: $3756  (3 positions across 1 accounts)
```

*(Example output; the account id is shortened here for width. Your numbers come from the live chain.)*

That is the whole loop: install, point at a public address, see normalized holdings. When you want your private accounts (Bybit, Binance), `setup` those too. Every connector uses **read-only** credentials, kept in your OS keychain, never written to disk and never sent anywhere except the exchange's own API. Then [wire it into Claude](#3-wire-up-claude-desktop) and ask *"what do I own?"* to get the same data as a chat-native dashboard.

### Non-interactive setup (scripts, Docker, CI)

`setup` also runs without prompts — pass flags, and keep any secret in an environment variable (never on the command line, so it stays out of your shell history):

```bash
# public-address connectors: everything via flags, zero secrets
headless-tracker setup solana --address=<base58> --dust=0.5
headless-tracker setup polymarket --proxy-wallet=0x... 

# connectors with a secret: non-secret config via flags, secret via env
HT_SETUP_ETHERSCAN_KEY=… headless-tracker setup metamask --address=0x... --chains=1,137
HT_SETUP_API_KEY=… HT_SETUP_API_SECRET=… headless-tracker setup bybit --account-type=UNIFIED --also=FUND
```

**Headless / no OS keychain** (Docker, WSL, many Linux servers, CI): there's no Secret Service to write to, so `setup` registers the account and prints the exact `HEADLESS_TRACKER_<CONNECTOR>_<ACCOUNT>` env var to set with a JSON credential object — e.g. `HEADLESS_TRACKER_SOLANA_<ADDR>='{"address":"…","dustThresholdUsd":0.5}'`. Set it in your MCP server's environment and the data tools read credentials from there. Nothing is ever written to disk.

## Interactive dashboard (live UI panel)

For hosts that support [MCP Apps](https://modelcontextprotocol.io/extensions/apps/overview) — Claude Desktop, ChatGPT, Goose, VS Code — say:

> Show my dashboard

The host renders a sandboxed iframe in the chat panel with three live tabs:

- **Portfolio** — total value KPIs, top positions table, allocation-by-symbol donut (top 7 + "Other" tail), warnings + failures
- **Weekly** — 7-day window delta KPIs, recent trades table, skipped-symbols disclosure (with reasons)
- **Risk** — concentration audit (single-position, venue, stablecoin reserve, prediction-market overweight) scored PASS / WARN / ALERT, by-venue donut

Plus a currency switcher (USD / EUR / GBP / HUF) and a refresh button. The iframe makes its own follow-up tool calls as the user clicks tabs — no extra prompting needed once it's open. Optional args:

> Open the dashboard in HUF, weekly tab

Implementation: `src/mcp/apps/dashboard/` (browser-side TS bundled into a single `dist/mcp-apps/dashboard.html` via `bun run build:apps`, ships with the package). The bundled artifact ships inside the npm package so users running `npx headless-tracker` don't need a build step.

If your host doesn't render MCP Apps yet, the `render_dashboard` tool still returns a textual confirmation. Use the [prompt cookbook](#prompt-cookbook) below as a fallback — same workflows, same data, just no live UI panel.

## Settings panel (live UI for setup + admin)

For setup that doesn't drop you into a terminal, ask:

> Open settings

The Settings MCP App opens with four tabs:

- **Accounts** — list of configured accounts with a Remove button (one-way confirm dialog; deletes from both the OS keychain and the registry).
- **Add Account** — forms for Bybit / Binance / MetaMask / Solana / Polymarket. Each form validates against the upstream API before persisting credentials. Explicit security disclosure at the top: credentials submitted via the form transit Claude Desktop's process en route to the keychain. **All five connectors use READ-ONLY credentials by design** (Bybit "Read" only, no Withdraw; Binance "Enable Reading" only, no Trade or Withdraw; Etherscan is a public-data rate-limit token; Polymarket proxy wallet is already public; Solana addresses are public on-chain identifiers). Worst-case leak = portfolio-read, never fund movement. For zero-trust, the CLI fl