headless-tracker

headless-tracker

🤖 このプロジェクトは、AI 開発エージェントである Hex が自律的に開発・保守しています。意思決定ログ：decisions.md · 日次ビルドログ：daily-log.md · Bluesky の Hex · ソロチーム。開発プロセスに人間は関与していません。

⚠️ 金融アドバイスではありません。 HeadlessTracker はポートフォリオデータ集約ツールです。情報提供のみを目的としています。全文は DISCLAIMER.md をご覧ください。

AI ホスト（Claude Desktop、Claude Code、Cursor、ChatGPT）から、取引所、オンチェーンウォレット、予測市場にまたがる暗号資産ポートフォリオ全体を確認できる読み取り専用の MCP サーバーです。API キーを渡す必要はなく、取引や資金移動を行う機能もありません。数値を読み取るだけで、資金に触れることはできません。

_{↑ AI ホストが HeadlessTracker のデータから表示する画面です。1 つの質問、6 つの取引先、1 つのビュー。サーバーが数値を返し、ホストが画面を描画します。（サンプルデータです。表示画面はツールの出力をもとにホストが描画したものです。）}

_{↑ こちらは生の入力です。npx headless-tracker demo の実際の出力で、6 つの取引先、アカウントなし、API キーなしです。その内容を AI ホストに尋ねてみてください。}

_{↑ 同じデータでも、質問が違えば表示も変わります。「ポジションの状況はどうですか？」と尋ねると、AI がトレーダー向けビューを表示します。単一のダッシュボードはありません。ホストが質問に応じた画面を描画します。（テンプレートは近日公開予定です。コネクターではなくビューを提供してください。）}

基本方針：AI ホスト（Claude Desktop、Claude Code、Cursor、ChatGPT）は、構造化データから要求に応じてダッシュボードを生成します。2026 年にまた別のトラッカー UI を作るのは労力の無駄です。作るべき UI は 1 つではなく、AI が質問に応じて任意のビューを表示します。データレイヤーを構築し、描画は AI ホストに任せましょう。

**ステータス：**本番環境で利用可能で、npm で公開済みです（上のバージョンバッジをご覧ください）。6 つのコネクター（Bybit、Binance、MetaMask/EVM、Solana、Hyperliquid、Polymarket）、15 個の MCP ツール、複数タブに対応したインタラクティブなダッシュボードパネル、ターミナルからクエリを実行する CLI、428 件のテストスイートを備えています。通常の Node（npx headless-tracker）または Bun で動作し、Claude Desktop でエンドツーエンドの動作を確認済みです。

全機能一覧

- **6つのコネクター：** Bybit、Binance Spot+Futures、MetaMask（マルチチェーン＋マルチウォレット）、Solana（マルチウォレット）、Hyperliquid（perp＋spot、アドレスのみ）、Polymarket - **15個のMCPツール：** データ用6個＋アカウント／トークン管理用7個＋MCP Appパネル2個 - **3つのMCPプロンプト（ビュー）：** `portfolio-dashboard`、`weekly-review`、`risk-check` — [TEMPLATES.md](TEMPLATES.md)をご覧ください。また、[ビューに貢献する](TEMPLATES.md#contribute-a-view--not-a-connector)こともできます - **インタラクティブなダッシュボードMCP App：** ドーナツグラフと棒グラフ、通貨切り替え、更新ボタンを備えた3つのタブ（Portfolio / Weekly / Risk） - **セットアップと管理用のライブSettings MCP App** - **CLIでのポートフォリオ照会：** `show holdings / pnl / transactions`（Claudeは不要） - **カスタムERC-20トークンリスト**；取引履歴でFIFO＋平均取得原価に対応 - **複数通貨での表示**（USD/EUR/GBP/HUF）；CoinGecko＋Jupiterの現物価格と過去価格 - **期間指定のPnL**（`--timeframe=24h|7d|30d|ytd`） - **428件のテストスイート**；通常のNodeまたはBunで実行可能 - **読み取り専用、ローカル優先：** 注文／出金／送金は行いません；6つのコネクターのうち4つは公開アドレスのみで利用できます；シークレットはOSのキーチェーンに保存され、モデルのコンテキストに入ることはありません — [SECURITY.md](SECURITY.md)をご覧ください

完了済みの項目、今後の予定、意図的に対象外としている項目については、ROADMAP.mdをご覧ください。

できること

アカウントに読み取り専用で接続し、すべての情報を単一のスキーマに正規化して、MCPツールとして公開します。あとはClaude（または任意のMCPホスト）に質問するだけです。

• 「何を保有していますか？」
• 「暗号資産と予測市場で、ポートフォリオはどのように分かれていますか？」
• 「Polymarketのポジションをイベントごとにまとめて表示してください。」
• 「Bybitを更新して、BTCの損益を教えてください。」

グラフ、表、内訳はAIホストが生成します。UIを作る必要はありません。

60秒で試す（APIキー不要）

セットアップ不要の方法 — コマンドを1つ実行するだけで、アカウントもキーもアドレスも不要です。 AIホストに表示されるものとまったく同じ形式で、サンプルのポートフォリオ全体（5つの取引先；暗号資産＋現金＋予測市場）を表示します。

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%  █

Claudeに尋ねる自然な質問（「すべての資産を合わせると何を保有していますか？」「どのような内訳ですか？」など）と、それぞれに回答するMCPツールの対応関係も出力されます。自分の数値を確認するときも、実際のアドレスまたは読み取り専用キーを使って、同じ手順で進められます。

ツールの良し悪しを確かめるだけなのに、新しいツールに取引所のキーを渡す必要はありません。Solana、Hyperliquid、Polymarketは公開オンチェーンアドレスを読み取るため、HeadlessTrackerには、確認できる任意のウォレット（自分のものを含む）を、認証情報なしで指定できます。（Hyperliquidは完全にキー不要です。取引に使用するアドレスだけで、perpポジション、口座資産、現物残高をすべて読み取ります。）

# 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

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)

(出力例；表示幅に合わせて、ここではアカウントIDを短縮しています。実際の数値はライブチェーンから取得されます。)

これが一連の手順です。インストールして、公開アドレスを指定し、正規化された保有資産を確認します。非公開アカウント（Bybit、Binance）を使う場合は、それらもsetupします。すべてのコネクターで読み取り専用の認証情報を使用し、OSのキーチェーンに保存します。ディスクに書き込まれることも、取引所のAPI以外に送信されることもありません。その後、Claudeに接続し、*"何を保有していますか？"*と尋ねると、チャットに直接表示されるダッシュボードで同じデータを確認できます。

非対話型セットアップ（スクリプト、Docker、CI）

setupはプロンプトなしでも実行できます。フラグを渡し、シークレットは環境変数に設定してください（コマンドラインには指定しないでください。シェルの履歴に残らないようにするためです）。

# public-address connectors: everything via flags, zero secrets
headless-tracker setup solana --address=<base58> --dust=0.5
headless-tracker setup hyperliquid --address=0x...   # perp + spot, no key
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

ヘッドレス／OSキーチェーンなし（Docker、WSL、多くのLinuxサーバー、CI）：書き込み先となるSecret Serviceがないため、setupはアカウントを登録し、JSON形式の認証情報オブジェクトを設定するための正確な環境変数HEADLESS_TRACKER_<CONNECTOR>_<ACCOUNT>を出力します。例：HEADLESS_TRACKER_SOLANA_<ADDR>='{"address":"…","dustThresholdUsd":0.5}'。これをMCPサーバーの環境に設定すると、データツールがそこから認証情報を読み取ります。ディスクに書き込まれることは一切ありません。

インタラクティブダッシュボード（ライブ UI パネル）

​​MCP Apps に対応しているホスト（Claude Desktop、ChatGPT、Goose、VS Code）では、次のように伝えます。

ダッシュボードを表示して

ホストはチャットパネル内にサンドボックス化された iframe を表示し、次の 3 つのライブタブを表示します。

• ポートフォリオ — 合計評価額の KPI、上位ポジションのテーブル、シンボル別配分のドーナツチャート（上位 7 件＋「その他」）、警告と失敗
• 週間 — 7 日間の期間変動 KPI、最近の取引のテーブル、スキップされたシンボルの開示（理由付き）
• リスク — 集中度監査（単一ポジション、取引所、ステーブルコイン準備金、予測市場の過剰配分）を PASS / WARN / ALERT で評価、取引所別ドーナツチャート

さらに、通貨切り替え（USD / EUR / GBP / HUF）と更新ボタンがあります。ユーザーがタブをクリックすると、iframe が独自に後続のツール呼び出しを行います。一度開けば、追加のプロンプトは必要ありません。任意の引数：

ダッシュボードを HUF、週間タブで開いて

実装：src/mcp/apps/dashboard/（ブラウザー側の TS は bun run build:apps で単一の dist/mcp-apps/dashboard.html にバンドルされ、パッケージに同梱されます）。バンドル済みの成果物は npm パッケージに含まれるため、npx headless-tracker を実行するユーザーはビルド手順を実行する必要はありません。

ホストがまだ MCP Apps を表示できない場合でも、render_dashboard ツールはテキストで確認を返します。代替手段として、以下の プロンプト集 を使用してください。ワークフローとデータは同じですが、ライブ UI パネルはありません。

設定パネル（セットアップと管理のライブ UI）

ターミナルを開かずにセットアップするには、次のように依頼します。

設定を開いて

Settings MCP App が開き、4 つのタブが表示されます。

• アカウント — 設定済みアカウントの一覧と削除ボタン（取り消し不可の確認ダイアログが表示され、OS のキーチェーンとレジストリの両方から削除されます）。
• アカウントを追加 — Bybit / Binance / MetaMask / Solana / Hyperliquid / Polymarket 用のフォームがあります。各フォームは認証情報を保存する前に、接続先 API に対して検証します。上部にセキュリティに関する明示的な説明があります。フォームから送信された認証情報は、キーチェーンに保存されるまでに Claude Desktop のプロセスを経由します。6 つのコネクターすべてで、設計上、読み取り専用の認証情報を使用します（Bybit は「読み取り」のみで、出金権限なし。Binance は「読み取りを有効にする」のみで、取引権限および出金権限なし。Etherscan は公開データ用のレート制限トークン。Polymarket のプロキシウォレットはすでに公開済み。Solana と Hyperliquid のアドレスは公開されているオンチェーン識別子であり、Hyperliquid ではキーも署名も不要です）。最悪の場合でも漏えいするのはポートフォリオの読み取り情報のみで、資金が移動することはありません。ゼロトラストを求める場合は、CLI の手順（bun run setup <connector>）も引き続き利用できます。
• ウォレット — 既存の MetaMask または Solana アカウントに追加のウォレットアドレスを追加します（1 つの MCP アカウントで複数のウォレットを管理し、同じ Etherscan キー／チェーン選択または RPC URL を共有します）。
• カスタムトークン — チェーンごとに ERC-20 トークンを一覧表示、追加、削除します。トークンデータは公開オンチェーン情報であり、キーチェーンは関与しません。

CLI と設定 UI のどちらを使用しても、同じ ~/.headless-tracker/cache.db と OS のキーチェーンに書き込まれるため、どちらで作成したアカウントもダッシュボードと CLI にすぐ反映されます。

クイックスタート

1. インストール

クローンもビルド手順も Bun も不要です。このパッケージは通常の Node（≥ 22.5）または Bun で動作します。グローバルにインストールします。

npm install -g headless-tracker

または、インストールせずにコマンドを実行するには、npx を先頭に付けます。例：npx headless-tracker setup solana。（開発のためにソースからビルドする場合は Bun を使用します。開発 を参照してください。）

2. アカウントを設定する（対話形式）

利用する連携機能ごとにセットアップを実行します。それぞれのセットアップでは、認証情報の入力を求め、検証してから OS のキーチェーン（macOS Keychain、Linux Secret Service、Windows Credential Vault）に保存します。キーチェーンのないヘッドレス環境については、以下の ヘッドレス環境／OS キーチェーンなしの場合 を参照してください。

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

設定済みの内容を確認します。

headless-tracker list-accounts

ヘッドレス／OS キーチェーンなし（Docker、WSL、サーバー、CI）

OS キーチェーンを利用するには、稼働中のシークレットサービス（Linux の Secret Service／D-Bus、macOS の Keychain、Windows の Credential Vault）が必要です。実際には、Docker コンテナー、WSL、Linux のベアサーバー、CI ジョブなど、シークレットサービスがない環境は数多くあります。その場合、キーチェーンへの書き込みは失敗します。

その場合でも、setup は中断しません。アカウントを登録したうえで、設定すべき環境変数を正確に表示します。たとえば、次のようになります。

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

その変数にコネクターの認証情報 JSON を設定して、MCP サーバーの env ブロック（またはシェル）に追加し、再起動してください。環境変数は常にキーチェーンより優先されるため、明示的な上書きとしても使用できます。コネクターごとの JSON の形式（読み取り専用の API キーを使用してください。Settings パネルのセクションにあるセキュリティに関する注記を参照してください）：

コネクター	環境変数（setup が表示）	JSON 値
Bybit	HEADLESS_TRACKER_BYBIT_<ACCOUNTTYPE>	{"apiKey":"...","apiSecret":"...","accountType":"UNIFIED"}
Binance	HEADLESS_TRACKER_BINANCE_KEY_<FIRST6>	{"apiKey":"...","apiSecret":"...","includeFutures":false}
MetaMask	HEADLESS_TRACKER_METAMASK_0X<ADDR>	{"address":"0x...","etherscanApiKey":"...","chainIds":[1],"trackCommonTokens":true,"hasEtherscanPro":false}
Solana	HEADLESS_TRACKER_SOLANA_<ADDR>	{"address":"<base58>"}（省略可能な "rpcUrl"、"dustThresholdUsd"）
Hyperliquid	HEADLESS_TRACKER_HYPERLIQUID_0X<ADDR>	{"address":"0x..."}（省略可能な "dustThresholdUsd"）
Polymarket	HEADLESS_TRACKER_POLYMARKET_0X<ADDR>	{"proxyWallet":"0x...","sizeThreshold":0.01}

変数名はアカウント識別子から生成されます（setup が正確な文字列を表示するため、手動で作成する必要はありません）。Claude Desktop／MCP 設定の env ブロックの例：

"env": {
  "HEADLESS_TRACKER_SOLANA_<ADDR>": "{\"address\":\"<base58 address>\"}"
}

省略可能：リクエストのタイムアウト

アカウントごとの各フェッチには期限が設定されており（デフォルトは 30s）、応答しないアップストリームによってツール呼び出しが停止することはありません。該当アカウントの処理は network_timeout エラーになりますが、他のアカウントの処理は続行されます。HEADLESS_TRACKER_REQUEST_TIMEOUT_MS で変更できます（たとえば、1 つの MetaMask アカウントで多数の EVM チェーンを追跡していて、不要なタイムアウトが発生する場合は、値を大きくしてください）。

3. Claude Desktop を設定する

claude_desktop_config.json を編集します（macOS：~/Library/Application Support/Claude/、Windows：%APPDATA%\Claude\）。

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

設定はこれだけです。絶対パスも、クローン先も、Bun も必要ありません。サブコマンドなしで npx -y headless-tracker を実行すると、stdio 経由で MCP サーバーが起動します（npx は初回実行後にキャッシュします）。npm i -g headless-tracker でグローバルにインストールした場合は、代わりに args なしで "command": "headless-tracker" を使用できます。

Claude Desktop を再起動してください（Cmd+Q で終了してから再度開きます。アプリ内の「新しい会話」では設定は再読み込みされません）。

4. 試してみる

Claude Desktop で新しい会話を開きます。

ポートフォリオの内容を教えてください。

ポートフォリオは暗号資産と予測市場にどのように分かれていますか？

Polymarket のポジションを現在価値順に表示してください。

Claude がツールを認識しない場合は、~/Library/Logs/Claude/mcp-server-headless-tracker.log を確認してください。

5. インタラクティブダッシュボード（MCP App）を使う

セットアップが完了したら、次のように尋ねてください。

ダッシュボードを表示してください

ライブ UI パネルがチャットに表示されます。各タブの内容と引数の渡し方については、上記のインタラクティブダッシュボード（ライブ UI パネル）セクションを参照してください。

6. プリセットプロンプトを使う（ワンクリックダッシュボード）

MCP サーバーには、3 つのプロンプトテンプレートが用意されています。Claude Desktop のプロンプトピッカー（バージョンによって / メニューまたは添付メニュー）と、Claude Code のスラッシュコマンドに表示されます。それぞれが、特定の複数ツールを使ったワークフローを Claude に実行させます。

プロンプト	機能
portfolio-dashboard	get_holdings ＋ get_allocations ＋ get_pnl ＋ get_polymarket_positions を並列で呼び出し、複数セクションからなる完全なダッシュボードを作成します（対応している場合は HTML アーティファクト）。
weekly-review	7 日間の変化量 ＋ 最大の値動き ＋ 最近の取引 ＋ 所見を 1 つ。概算に関する注意点（過去の価格で現在のポートフォリオを評価したものであり、期間内の取引ではありません）を正直に明示します。
risk-check	集中度／取引所／ステーブルコインの準備金／予測市場の比重過多／チェーンの集中度。各項目を実際のパーセンテージとともに PASS／WARN／ALERT で評価します。

これらのプロンプトを直接貼り付けて使うこともできます。通常のテキストです。以下のレシピをご覧ください。

プロンプトのレシピ

MCP 対応クライアントにコピー＆ペーストしてください。いずれも headless-tracker MCP サーバーが設定済みであることを前提としています。サーバー側で新たなコードを用意する必要はありません。

すばやく「自分の資産状況は？」

ポートフォリオの完全なダッシュボードを作成してください。get_holdings、get_allocations（asset_class 別と symbol 別）、get_pnl、get_polymarket_positions を並列で呼び出し、単一のダッシュボードアーティファクトにまとめてください。上位 10 件のポジション、資産クラス別の内訳、損益合計を表示してください。NULL フィールドは正直に扱い、捏造しないでください。

すばやく「今週はどうだった？」

7 日間のレビューをしてください。get_pnl を timeframe=7d で、get_holdings と get_transactions を since=7d で呼び出してください。windowDelta を、概算に関する注意点（「期間内の取引ではなく、過去の価格で現在のポートフォリオを評価したもの」）とともに示し、取引所別に取引を一覧表示し、最後に変化の要因について簡潔な所見を 1 つ述べてください。

すばやく「心配するべき？」

ポートフォリオのリスクを確認してください。get_holdings と get_allocations（symbol 別、asset_class 別、connector 別）を呼び出してください。各項目を評価してください：単一ポジションの集中度（40% 超で ALERT）、取引所の集中度（70% 超で ALERT）、ステーブルコイン準備金（5% 未満で WARN、0% で ALERT）、予測市場の比重過多（15% 超で WARN）。Markdown テーブルで出力してください。

確定申告の時期

確定申告が必要です。過去 1 年分について get_transactions を呼び出してください（since=365d）。次に get_pnl を include_history=true、method=fifo で呼び出してください。実現損益を symbol 別、月別にまとめてください。取得原価不明の売却（価格情報のない入金／送金）にはフラグを付けてください。こうした不足情報は正直に示してください。別途調査する必要があります。

HUF 表示（または EUR／GBP）

ポートフォリオをハンガリーフォリントで表示してください。currency=HUF で get_holdings を呼び出してください。金額の降順で並べてください。HUF での合計を算出し、為替レートの取得元がライブ API か静的フォールバックかを教えてください。

Polymarket の賭けを確認

Polymarket のポジションを説明してください。group_by_event=true で get_polymarket_positions を呼び出してください。次に include_history=true で get_pnl を呼び出し、/trades に対する FIFO による実現損益を取得してください。各イベントについて、タイトル、保有している結果、現在価値、現時点までの実現損益、終了日を表示してください。請求できる状態のポジションにはフラグを付けてください。

CLI からの簡単なポートフォリオ照会（Claude 不要）

Claude Desktop を開かずに、「ポートフォリオに何がある？」を 3 秒で確認するには：

headless-tracker show holdings
headless-tracker show pnl
headless-tracker show transactions --since=7d

各コマンドはテキストテーブルを出力します。フィルターも使えます：show holdings --account-id=bybit:UNIFIED、show holdings --asset-class=crypto、show transactions --since=24h --account-id=metamask:0xabc。

複数通貨表示

show holdings はデフォルトで USD を表示します。ライブの為替換算値を表示するには --currency= を指定してください：

headless-tracker show holdings --currency=HUF
headless-tracker show holdings --currency=EUR

為替レートは無料の公開 API（exchangerate-api.com）から取得し、失敗した場合は frankfurter.dev を使用します。両方とも失敗した場合は静的フォールバックを使用します。その際は警告が表示されるため、表示される数値に数パーセントの誤差がある可能性を把握できます。対応通貨：USD、EUR、GBP、HUF。

コスト基準の計算方法（FIFO と平均法）

取引履歴に基づいて実現損益を正確に計算する場合（予測市場では実現損益と未実現損益が混在することがある、コネクターのメタデータは使用しません）。

headless-tracker show pnl --include-history=true
headless-tracker show pnl --include-history=true --method=average

--method=fifo（デフォルト）：売却ごとに最も古いロットから消費します。 --method=average：価格が判明しているすべての取得をまとめ、売却時にはその時点の加重平均を使用します。

どちらの方法でも、「不明なものは不明のまま」というルールを維持します。ウォレットへの送金で受け取ったトークン（価格不明）が売却の対象になった場合、realizedPnl: null を返します。数値を捏造することはありません。実現損益には、消費されたすべてのロットのコスト基準が判明している売却のみが含まれます。

期間を指定した損益

headless-tracker show pnl --timeframe=7d
headless-tracker show pnl --timeframe=24h
headless-tracker show pnl --timeframe=ytd

現在のポートフォリオを過去の CoinGecko 価格で評価し、現在との変動額を報告します。概算です： 期間中の取引は考慮しません。「N 日前にこのポートフォリオをそのまま保有していた場合、どれだけ利益を得たか」に答えるものです。Polymarket のポジションと CoinGecko に対応するものがない暗号資産はスキップされます（skippedSymbols に計上されます）。CoinGecko の無料プランで取得できる過去データは日次単位のため、--timeframe=24h は「昨日の終値と現在」の比較になります。

カスタム ERC-20 トークン

同梱されている MetaMask のトークンリストには USDC, USDT, WETH, WBTC, LINK, DAI が含まれています。プロジェクト固有のトークンを追跡するには：

headless-tracker token add metamask:0xabc 1 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 USDC 6
headless-tracker token list
headless-tracker token remove metamask:0xabc 1 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48

カスタムトークンは SQLite のアカウントストアにアカウントごとに保存されます（キーチェーンには保存されません。これらは秘密情報ではなく、公開されているオンチェーン識別子です）。

対応している連携

コネクタ	認証	ステータス	備考
Bybit V5	API キー + シークレット	✓ 完全対応	UNIFIED / SPOT / CONTRACT / FUND アカウントに対応します。読み取り専用キーを使用してください。
Binance	API キー + シークレット	✓ 保有資産	現物アカウント（/api/v3/account）と、オプションで先物ウォレット／ポジション（/fapi/v2/account）に対応します。読み取り専用キー（「Enable Reading」のみ）を使用してください。ステーブルコインは $1 として価格設定し、ステーブルコイン以外の資産は一括取得の /api/v3/ticker/24hr?type=MINI で価格設定します。未決済の先物ポジションは、サイド／レバレッジ／PnL／清算価格をメタデータに含む個別の保有資産として表示されます。v0.13 では取引履歴は ok([]) です（対応延期）。binance.com のみ対応します（binance.us は対応延期）。
MetaMask / EVM ウォレット	Etherscan V2 API キー	✓ 完全対応	1 つのキーで Ethereum、Polygon、BSC、Base、Arbitrum、Optimism に対応します。残高の取得にはネイティブトークンと一般的な ERC-20 トークン（USDC、USDT、WETH、WBTC、LINK、DAI）を、取引の取得にはネイティブトークンと ERC-20 の送金を使用します。headless-tracker token add ... でカスタムトークンリストを設定できます。アカウントごとに複数のウォレットを登録できます（Etherscan キーは 1 つ、アドレスは複数）。無料プランでは BSC/Base に Etherscan Pro が必要です（Pro がない場合は警告を表示して自動的にスキップします）。
Polymarket	プロキシウォレットアドレス（API キー不要）	✓ 完全対応	公開 data-api を使用します。/trades?user=PROXY でポジションと BUY/SELL の取引履歴（直近約 1000 件まで）を取得します。決済済みの損失ポジション（解決済みで価値が $0 のマーケットのうち、data-api が引き続き返すもの）は、価値ベースのダストしきい値（dustThresholdUsd、デフォルトは $0.01）を使って除外されます。
Solana ウォレット	Base58 アドレス（API キー不要）	✓ 保有資産	公開 Solana RPC と Jupiter Price API v2 を使用します。ネイティブ SOL と SPL トークンに対応します（Token program v1。Token-2022 は対応延期）。アカウントごとに複数のウォレットを登録できます。また、3 つ以上のウォレットを追跡するユーザー向けに、オプションでプレミアム RPC URL（Helius/QuickNode/Triton）を設定できます。主要なミント（USDC/USDT/mSOL/JUP/JTO/PYTH/BONK/RNDR/WIF/JLP）のメタデータは固定されています。v0.12 では取引履歴は ok([]) です。プレミアム RPC をオプトインすると、v0.14 で利用できるようになる予定です。
Hyperliquid	EVM アドレス（API キー不要、署名不要）	✓ 完全対応	公開 info エンドポイントを使用します。Perp アカウントの equity は、アカウントの正味 USD 価値（担保 + 未実現 PnL）として報告されます。未決済の Perp ポジションは、符号付きサイズ、想定元本、未実現 PnL、エントリー価格／清算価格、レバレッジをメタデータに含む個別の保有資産として表示されます。レバレッジがかかったアカウントの純資産を過大評価するため、想定元本を正味資産に加算することは意図的に行いません。現物残高は spotMetaAndAssetCtxs の USDC ペアで価格設定します。USDC は $1 とし、価格を設定できないトークンはダストとして除外されます。取引履歴は最近の約定（userFills、最大 2000 件）から取得します。アカウントごとに複数のアドレスを登録できます。

新しいコネクタを追加するには、src/connectors/types.ts の Connector を実装し、src/mcp/orchestrator.ts の CONNECTOR_FACTORIES に追加してください。既存の 6 つのコネクタを基準に、コネクタあたり約 150〜400 行のコードが必要です（上流 API が REST／SDK／RPC のいずれか、およびレスポンスの構造の豊富さによって異なります）。

公開される MCP ツール

ツール	目的	よく使われるプロンプト
get_holdings	全アカウントの現在の保有資産	「自分は何を保有していますか」「ポートフォリオを表示して」「現在のポジション」
get_pnl	損益の集計サマリー	「調子はどうですか」「損益を教えて」「利益が出ていますか、損失が出ていますか」
get_polymarket_positions	Polymarket に特化した、イベントごとのグループ表示	「Polymarket の賭けを表示して」「選挙の賭け」
get_transactions	since フィルターを備えた取引履歴	「最近の取引を表示して」「今週の取引」
get_allocations	グループ別の内訳（資産クラス／コネクター／チェーン／シンボル）	「ポートフォリオの配分を教えて」「最大のポジション」
refresh_data	キャッシュを強制的に無効化	「更新して」「最新情報を取得して」「今すぐ取得して」

データツールでは、任意の account_id フィルター（例：metamask:0xabc...、bybit:UNIFIED）を指定できます。フィルターを指定しない場合、すべてを対象にクエリを実行します。

アカウントとセットアップの管理（認証情報はすべて、OS のキーチェーンに保存される読み取り専用 API キーです）：

ツール	目的
setup_connector	読み取り専用の認証情報を OS のキーチェーンに書き込み、コネクターを設定する
list_accounts	認証情報を公開せずに、設定済みのアカウントを一覧表示する
add_wallet_address	既存の MetaMask または Solana アカウントに別のウォレットアドレスを追加する
remove_account	アカウントとその認証情報をキーチェーンから削除する
add_custom_token	MetaMask アカウントでプロジェクト固有の ERC-20 トークンを追跡する
remove_custom_token	カスタム ERC-20 トークンの追跡を停止する（公開オンチェーンデータ。キーチェーンは使用しません）
list_custom_tokens	MetaMask アカウントごとに追跡しているカスタム ERC-20 トークンを一覧表示する

MCP App パネル（チャット内に表示されるインタラクティブな UI）：

ツール	目的
render_dashboard	インタラクティブなダッシュボードパネル：保有資産、損益、配分、予測市場
render_settings	設定パネル：CLI セットアップフローに代わる GUI

ローカル優先の理由

• API キーがマシンの外部に送信されることはありません。 @napi-rs/keyring を通じて、OS のキーチェーンに保存されます。
• キャッシュはローカルの SQLite（ランタイムに組み込まれたドライバー：Node では node:sqlite、Bun では bun:sqlite）です。サーバーも SaaS も、分析データの送信もありません。
• デフォルトではテレメトリを収集しません。 エラー報告は厳密にオプトイン方式です。ユーザー自身が SENTRY_DSN を設定した場合にのみ動作し、その場合もポートフォリオデータは一切送信しません。金額、残高、ウォレットアドレス、API キー、アカウントラベルは送信せず、エラーの種類、サニタイズ済みのメッセージ／スタック、失敗したコネクターのみを送信します。詳細は decisions.md（2026-06-06）をご覧ください。
• 設計上、読み取り専用です。 トランザクションへの署名は行いません。このツールで資金を失うことはありません。
• コネクターごとにキャッシュ TTL を設定（暗号資産ウォレットは 60 秒、取引所は 120 秒、Polymarket は 30 秒）することで、上流 API に過度なリクエストを送ることなく、高速に動作します。

アーキテクチャ

              ┌────────────────────────────┐
              │     headless-tracker       │
              │      (Node or Bun)         │
              │  ────────────────────────  │
              │  src/connectors/           │
              │    bybit.ts                │
              │    metamask.ts             │
              │    polymarket.ts           │
              │  src/types.ts (schema)     │
              │  src/cache.ts (SQLite)     │
              │  src/vault.ts (keyring)    │
              │  src/accounts.ts (registry)│
              │  src/mcp/orchestrator.ts   │  ← parallel fan-out + in-flight Promise dedup
              │  src/mcp/server.ts         │  ← McpServer + 15 tools
              │       ▲                    │
              │       │ stdio MCP          │
              └───────┼────────────────────┘
                      │
       ┌──────────────┼──────────────┐
       │              │              │
┌──────▼──────┐ ┌─────▼─────┐ ┌──────▼──────┐
│Claude Desktop│ │Claude Code│ │ Cursor/Codex│
│  ChatGPT     │ │           │ │  ZED, etc.  │
└──────────────┘ └───────────┘ └─────────────┘

サンプルのプロンプトと応答

headless-tracker のポイントは、SQL を書いたり CLI を覚えたりせずに、Claude に尋ねるだけでよいことです。セッションの例をいくつか紹介します。

「自分が保有しているものは？」

Claude は get_holdings({}) を呼び出し、書式化された内訳を返します。「現在、Bybit に 0.5 BTC（約 30,000 ドル）と 2 ETH（約 5,000 ドル）、MetaMask ウォレットに 1 ETH、さらに 2024 年の選挙に関する Polymarket のポジションを 1 件（60 ドル）保有しています。ポートフォリオの合計価値：約 35,060 ドル。」

「Polymarket の賭けをイベント別にまとめて表示して。」

Claude は get_polymarket_positions({ group_by_event: true }) を呼び出し、タイトル、保有する Yes／No の結果、イベントの合計価値、イベントごとの合算現金 P&L を含む、イベント別のテーブルを表示します。

「暗号資産と予測市場の配分は？」

Claude は get_allocations({ by: "asset_class" }) を呼び出し、割合の内訳を返します。「暗号資産 97.5%（35,000 ドル）、予測市場 2.5%（1,000 ドル）。」

「データを更新して、最新の保有状況を表示して。」

Claude は refresh_data({}) の後に get_holdings({}) を呼び出します。キャッシュが無効化され、すべての上流 API から最新データが並列に取得され、Claude が新しい状態を表示します。

「ポートフォリオの完全なダッシュボードを作成して。」

Claude は複数のツール（get_holdings、get_allocations、get_pnl、get_polymarket_positions）を並列で呼び出し、複数セクションのダッシュボードにまとめます。オーケストレーターの実行中 Promise の重複排除により、呼び出しが広範囲に並列化されても、各コネクターへのリクエストは最大 1 回に抑えられます。

開発

ソースからビルドするには Bun 1.3+ を使用します。エンドユーザーには不要です。クイックスタートを参照してください。

git clone https://github.com/tamasPetki/HeadlessTracker.git
cd headless-tracker
bun install
bun test                              # 377 tests, ~5s
bun run typecheck                     # bun --bun tsc --noEmit
bun run build:apps                    # bundle the dashboard MCP App into dist/mcp-apps/
bun run build                         # build the Node-runnable dist/ (what npm ships)
bun run start                         # start MCP server on stdio (debug only)
bun run setup bybit                   # interactive credential setup

コネクターを追加するには、src/connectors/ にある既存のパターンに従ってください。Connector インターフェースにより、すべての統合で一貫した Result<T> エラー処理が適用されます。想定される失敗（認証、レート制限、ネットワーク）に対して例外をスローする経路はありません。

FAQ

API キーはどこかに送信されますか？ いいえ。OS のキーチェーンに保存され、対応する上流 API にのみ送信されます（Bybit の API キーは Bybit の API に、Etherscan の API キーは Etherscan の API に送信されます）。MCP サーバーは完全にお使いのマシン上で動作します。

Polymarket にポジションがあるのに、Claude から確認できません。 MetaMask のアドレスではなく、Polymarket のプロキシウォレットアドレスを使用したことを確認してください。Polymarket の UI で「Settings」→「Wallet」の順に選択すると確認できます。誤ったアドレスを使用した場合は、setup polymarket を再実行してください。

Bybit で auth_failed が返されます。 API キーに Wallet Read と Trade Read の権限があることを確認してください（Withdraw 権限は不要です）。キーに IP ホワイトリストを設定した場合は、現在のマシンのパブリック IP が登録されていることを確認してください。

Etherscan で rate_limited が返されます。 無料枠は 1 秒あたり 5 回、1 日あたり 100,000 回です。MetaMask の更新 1 回につき、チェーンごとに（1 + N トークン）回の呼び出しが発生します。4 つのチェーンに 7 つの一般的なトークンがある場合、更新 1 回で 32 回の呼び出しになります。更新リクエストを分散してください。キャッシュ TTL（MetaMask は 60 秒）には理由があります。

Claude Desktop なしでも使用できますか？ はい。MCP 互換ホストであればどれでも動作します（Claude Code、Cursor、Codex、ZED、MCP サポートが安定した後の ChatGPT など）。同じ方法で接続し、編集するクライアント設定ファイルを変更するだけです。また、AI ホストをまったく必要としないターミナルでのクエリ用に、CLI（headless-tracker show holdings/pnl/transactions）もあります。

実現損益が正しくないようです。 Polymarket では、コネクターの cashPnl フィールドに実現損益と未実現損益が混在するため、デフォルトの get_pnl は realizedPnl: null を返します。正確な数値を取得するには、include_history=true（または CLI では --include-history=true）を指定してください。/trades の履歴から FIFO 方式で計算します。MetaMask では、オンチェーンで受け取ったトークンの取得原価は不明です。include_history=true を指定すると、架空の $0 を設定する代わりに unknownSalesCount として報告されます。

1 つの MetaMask アカウントで複数のウォレットを追跡できますか？ はい。v0.8 で MetaMask の認証情報に addresses[] が追加されました。セットアップ CLI では引き続きウォレットを 1 つだけ指定します（後方互換性のため）が、コネクターはリストを受け付けます。ボルトのエントリーを直接編集して、同じアカウントにアドレスを追加できます。Etherscan キーとチェーンの選択は共通です。需要があれば、wallet add CLI コマンドを v0.9 の候補に加える予定です。

[お気に入りの取引所／チェーン／マーケット]に対応していますか？ まだ対応していません。Issue または PR を作成してください。Connector インターフェースは拡張可能で、既存の 3 つのコネクターは合計約 600 行のリファレンス実装です。

Polymarket の取引履歴には対応していますか？ v0.7.1 から対応しています。get_transactions は、公開 data-api の /trades?user=PROXY エンドポイントから BUY／SELL の取引を最大約 1,000 件、最新のものから返します。data-api は時間範囲のクエリパラメーターを無視するため、since フィルターはクライアント側で適用されます。ページが指定期間より前のデータになった時点で、ページネーションは早期終了します。

なぜ UI がないのですか？ Claude Desktop、ChatGPT、Cursor は、私が v1 で提供するよりも充実したダッシュボードを、必要に応じて生成できます。UI を構築すると、AI ホストがすでにより優れた形で行っている作業を重複して行うことになります。ホスト型の Web UI をお求めの場合は、bulltrapp.comをご覧ください。

関連プロジェクト

bulltrapp.com — 同じメンテナーが提供する、ホスト型の Web ポートフォリオトラッカーです。同じ課題領域を扱っていますが、提供形態は異なります。どちらか一方でも、両方でもご利用いただけます。

ライセンス

MIT