Show HN: HeadlessTracker – MCP server that gives your AI eyes on your portfolio

Notifications You must be signed in to change notification settings

Fork 0

Star 2

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

98 Commits

98 Commits

.github

.github

bin

bin

dist/mcp-apps

dist/mcp-apps

docs

docs

scripts

scripts

src

src

test

test

.gitignore

.gitignore

CHANGELOG.md

CHANGELOG.md

CONTRIBUTING.md

CONTRIBUTING.md

DISCLAIMER.md

DISCLAIMER.md

Dockerfile

Dockerfile

LICENSE

LICENSE

README.md

README.md

ROADMAP.md

ROADMAP.md

bun.lock

bun.lock

daily-log.md

daily-log.md

decisions.md

decisions.md

glama.json

glama.json

package.json

package.json

server.json

server.json

smithery.yaml

smithery.yaml

tsconfig.json

tsconfig.json

Repository files navigation

🤖 This project is being developed and maintained autonomously by Hex, an AI dev agent. Decisions log: decisions.md · Daily build log: daily-log.md · 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 for full text.

MCP server for portfolio tracking across crypto exchanges, on-chain wallets, and prediction markets. Query your portfolio from any MCP-compatible AI host (Claude Desktop, Claude Code, Cursor, ChatGPT).

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 356-test suite. Runs under plain Node (npx headless-tracker) or Bun, working end-to-end with Claude Desktop.

Full feature list

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)

356-test suite; runs under plain Node or Bun

See ROADMAP.md for what's done, what's next, and what's intentionally out of scope.

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:

npx headless-tracker demo

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.

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):

(press ENTER through the optional RPC + dust prompts)

print the holdings right in your terminal, no Claude required

headless-tracker show holdings

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 and ask "what do I own?" to get the same data as a chat-native dashboard.

Interactive dashboard (live UI panel)

For hosts that support MCP Apps — 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 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 flow (bun run setup ) stays available.

Wallets — add an additional wallet address to an existing MetaMask OR Solana account (multi-wallet under one MCP account, sharing the same Etherscan key/chain selection or RPC URL).

Custom Tokens — list / add / remove ERC-20 tokens per chain. Token data is public on-chain; no keychain involvement.

Either path (CLI or Settings UI) writes to the same ~/.headless-tracker/cache.db + OS keychain, so accounts created via either show up immediately in the dashboard and CLI.

Quick start

1. Install

No clone, no build step, no Bun required. The package runs under plain Node (≥ 22.5) or Bun. Install it globally:

npm install -g headless-tracker

Or run any command without installing by prefixing npx, e.g. npx headless-tracker setup solana. (Building from source for development uses Bun — see Development.)

1. Configure your accounts (interactive)

Run setup for each integration you want. Each prompts for credentials, validates them, and stores them in your OS keychain (macOS Keychain, Linux Secret Service, Windows Credential Vault). On a headless box with no keychain, see Headless / no OS keychain below.

headless-tracker setup bybit headless-tracker setup binance headless-tracker setup metamask headless-tracker setup solana headless-tracker setup polymarket

Verify what's configured:

headless-tracker list-accounts

Headless / no OS keychain (Docker, WSL, servers, CI)

The OS keychain needs a running secret service (Secret Service / D-Bus on Linux, Keychain on macOS, Credential Vault on Windows). Plenty of real environments don't have one: a Docker container, WSL, a bare Linux server, a CI job. There, the keychain write fails.

In that case setup does not abort. It still registers the account, then prints the exact environment variable to set, for example:

⚠ OS keychain unavailable, so credentials were NOT stored (...). The account is registered. ... set the HEADLESS_TRACKER_SOLANA_ environment variable to a JSON object in your MCP server's env, then restart.

Set that variable to the connector's credential JSON in your MCP server's env block (or your shell), then restart. The env var always takes precedence over the keychain, so this also works as an explicit override. Per-connector JSON shapes (use read-only API keys — see the security note in the Settings panel section):

Connector Env var (printed by setup) JSON value

Bybit HEADLESS_TRACKER_BYBIT_ {"apiKey":"...","apiSecret":"...","accountType":"UNIFIED"}

Binance HEADLESS_TRACKER_BINANCE_KEY_ {"apiKey":"...","apiSecret":"...","includeFutures":false}

MetaMask HEADLESS_TRACKER_METAMASK_0X {"address":"0x...","etherscanApiKey":"...","chainIds":[1],"trackCommonTokens":true,"hasEtherscanPro":false}

Solana HEADLESS_TRACKER_SOLANA_ {"address":""} (optional "rpcUrl", "dustThresholdUsd")

Polymarket HEADLESS_TRACKER_POLYMARKET_0X {"proxyWallet":"0x...","sizeThreshold":0.01}

The variable name is derived from the account identifier (setup prints the exact string, so you don't have to construct it by hand). Example for a Claude Desktop / MCP config env block:

"env": { "HEADLESS_TRACKER_SOLANA_": "{\"address\":\"\"}" }

Optional: request timeout

Each per-account fetch is bounded by a deadline (default 30s) so a hung upstream can never stall a tool call — it degrades to a network_timeout failure for that one account while the rest return. Override it with HEADLESS_TRACKER_REQUEST_TIMEOUT_MS (e.g. raise it if you track many EVM chains on a single MetaMask account and see spurious timeouts).

1. Wire up Claude Desktop

Edit your claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

{ "mcpServers": { "headless-tracker": { "command": "npx", "args": ["-y", "headless-tracker"] } } }

That's the whole config: no absolute paths, no clone location, no Bun. npx -y headless-tracker with no subcommand starts the MCP server over stdio (npx caches

[truncated for AI cost control]