headless-tracker

headless-tracker

🤖 本项目由 AI 开发 Agent Hex 自主开发和维护。决策日志：decisions.md · 每日构建日志：daily-log.md · 在 Bluesky 上关注 Hex · 独立团队。开发过程中没有人类参与。

⚠️ 不构成财务建议。 HeadlessTracker 是一款投资组合数据聚合工具，仅供参考。完整内容请参阅 DISCLAIMER.md。

一个只读 MCP 服务，让你的 AI 宿主（Claude Desktop、Claude Code、Cursor、ChatGPT）查看你在交易所、链上钱包和预测市场中的全部加密货币投资组合——无需向它提供 API 密钥，也无法进行交易或转移资金。它只读取数字，无法触碰资金。

_{↑ AI 宿主根据 HeadlessTracker 的数据渲染出的内容——一个问题、六个平台、一个视图。服务返回数字，宿主绘制图表。（示例数据；此视觉效果由宿主基于工具输出渲染。）}

_{↑ 以及原始输入：npx headless-tracker demo 的实际输出——六个平台，无需账户和 API 密钥。然后向你的 AI 宿主询问相关信息。}

_{↑ 相同数据，不同问题。询问“我的持仓表现如何？”，AI 就会渲染出交易者视图。没有固定的仪表板——宿主会绘制你要求的视图。（模板即将推出：欢迎贡献视图，而非连接器。）}

核心观点：AI 宿主（Claude Desktop、Claude Code、Cursor、ChatGPT）可以根据结构化数据按需生成仪表板。在 2026 年再构建一款追踪器 UI 是白费功夫——没有唯一的 UI 需要构建，AI 会渲染你想要的任何视图。构建数据层，让 AI 宿主负责渲染。

状态： 已达到生产就绪状态，并已在 npm 上线（版本见上方徽章）。包含六个连接器（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（永续合约 + 现货，仅需地址）、Polymarket - **15 个 MCP 工具：**6 个数据工具 + 7 个账户／代币管理工具 + 2 个 MCP App 面板 - **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），包含环形图和柱状图、货币切换器、刷新按钮 - **实时设置 MCP App**，用于配置和管理 - **CLI 投资组合查询：**`show holdings / pnl / transactions`（无需 Claude） - **自定义 ERC-20 代币列表**；基于交易历史计算 FIFO + 平均成本 - **多币种显示**（USD/EUR/GBP/HUF）；通过 CoinGecko + Jupiter 获取现货价和历史价格 - **按时间范围统计盈亏**（`--timeframe=24h|7d|30d|ytd`） - **包含 428 项测试的测试套件**；可在原生 Node 或 Bun 下运行 - **只读且本地优先：**不支持下单／提现／转账；6 个连接器中有 4 个只需公开地址；密钥保存在操作系统密钥链中，绝不会进入模型的上下文——参见 [SECURITY.md](SECURITY.md)

有关已完成事项、后续计划及有意排除的范围，请参见 ROADMAP.md。

功能介绍

以只读方式连接你的账户，将所有数据统一为单一架构，并将其作为 MCP 工具提供。然后你可以向 Claude（或任何 MCP 宿主）提问：

• “我有哪些资产？”
• “我的投资组合在加密货币和预测市场之间如何分配？”
• “按事件分组显示我的 Polymarket 仓位。”
• “刷新 Bybit，并告诉我 BTC 的盈亏。”

AI 宿主会生成图表、表格和明细。你无需构建 UI。

60 秒快速试用（无需 API 密钥）

**零配置版本——只需一条命令，无需账户、密钥，甚至无需地址。**查看完整的示例投资组合（五个平台；加密货币 + 现金 + 预测市场），其呈现方式与你的 AI 宿主收到的内容完全一致：

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 完全无需密钥——永续合约仓位、账户净值和现货余额都只需读取你用于交易的地址。）

# 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。每个连接器都使用只读凭据，这些凭据保存在操作系统密钥链中，不写入磁盘，也不会发送到交易所自有 API 之外的任何地方。然后将其接入 Claude，并询问*“我有哪些资产？”*，即可获得与聊天原生仪表板相同的数据。

非交互式设置（脚本、Docker、CI）

setup 也可以在无提示的情况下运行——传入标志，并将任何密钥放在环境变量中（切勿放在命令行上，以免记录在 shell 历史中）：

# 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

无头模式／无操作系统密钥链（Docker、WSL、许多 Linux 服务器、CI）：由于没有可供写入的 Secret Service，setup 会注册账户，并打印需要设置的确切 HEADLESS_TRACKER_<CONNECTOR>_<ACCOUNT> 环境变量，其值为 JSON 凭据对象，例如 HEADLESS_TRACKER_SOLANA_<ADDR>='{"address":"…","dustThresholdUsd":0.5}'。在 MCP 服务的环境中设置该变量，数据工具便会从中读取凭据。任何内容都不会写入磁盘。

交互式仪表板（实时 UI 面板）

对于支持 MCP Apps 的宿主 — Claude Desktop、ChatGPT、Goose、VS Code — 可以说：

显示我的仪表板

宿主会在聊天面板中渲染一个沙盒化 iframe，其中包含三个实时标签页：

• Portfolio（投资组合） — 总价值 KPI、主要持仓表、按币种分配的环形图（前 7 项 + “其他”尾项）、警告和故障
• Weekly（每周） — 7 天窗口变化 KPI、近期交易表、跳过的币种说明（含原因）
• Risk（风险） — 集中度审查（单一持仓、交易场所、稳定币储备、预测市场超配），评级为 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 会打开，包含四个标签页：

• Accounts（账户） — 显示已配置账户的列表，并提供 Remove 按钮（单向确认对话框；会从 OS 钥匙串和注册表中删除）。
• Add Account（添加账户） — 提供 Bybit / Binance / MetaMask / Solana / Hyperliquid / Polymarket 表单。每个表单都会先通过上游 API 验证凭据，再保存凭据。表单顶部会明确说明安全事项：通过表单提交的凭据在送往钥匙串的过程中会经过 Claude Desktop 进程。这六个连接器均按设计使用只读凭据（Bybit 仅启用“Read”，不启用 Withdraw；Binance 仅启用“Enable Reading”，不启用 Trade 或 Withdraw；Etherscan 是用于限制请求频率的公共数据令牌；Polymarket 代理钱包本身已公开；Solana 和 Hyperliquid 地址是公开的链上标识符 — Hyperliquid 完全不需要密钥或签名）。最坏情况下发生泄露，也只能读取投资组合，无法转移资金。若要实现零信任，仍可使用 CLI 流程（bun run setup <connector>）。
• Wallets（钱包） — 为现有 MetaMask 或 Solana 账户添加其他钱包地址（在单个 MCP 账户下管理多个钱包，共用同一个 Etherscan 密钥 / 链选择或 RPC URL）。
• Custom Tokens（自定义代币） — 按链列出、添加或移除 ERC-20 代币。代币数据是公开的链上数据；不涉及钥匙串。

无论选择哪种方式（CLI 或 Settings 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. 配置账户（交互式）

对每个要使用的集成运行 setup。每项设置都会提示输入凭据、验证凭据，并将其存储在 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.

将此变量设为 MCP 服务的 env 块（或 Shell）中的连接器凭据 JSON，然后重启。环境变量始终优先于密钥链，因此也可用作显式覆盖。各连接器的 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 覆盖此设置（例如，若你在单个 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 全局安装，也可以仅使用 "command": "headless-tracker"，不设置 args。

重启 Claude Desktop（按 Cmd+Q，然后重新打开——应用内的“新建对话”不会重新加载配置）。

4. 试用

在 Claude Desktop 中开启新对话：

我的投资组合里有什么？

我的投资组合中，加密货币和预测市场的占比如何？

显示我的 Polymarket 持仓，并按当前价值排序。

如果 Claude 看不到这些工具，请检查 ~/Library/Logs/Claude/mcp-server-headless-tracker.log。

5. 使用交互式仪表板（MCP App）

设置完成后，询问：

显示我的仪表板

实时 UI 面板会在聊天中弹出。有关各个标签页的内容以及如何传递参数，请参阅上文的交互式仪表板（实时 UI 面板）部分。

6. 使用预设提示词（一键式仪表盘）

MCP 服务附带三个提示词模板。它们会显示在 Claude Desktop 的提示词选择器中（/ 菜单或附件菜单，具体取决于版本），也会在 Claude Code 中显示为斜杠命令。每个提示词都会引导 Claude 完成特定的多工具工作流：

提示词	功能
portfolio-dashboard	并行调用 get_holdings + get_allocations + get_pnl + get_polymarket_positions，并生成完整的多分区仪表盘（支持时生成 HTML 工件）。
weekly-review	7 天窗口变化 + 变动最大的项目 + 最近交易 + 一条观察。坦诚说明近似计算的注意事项（按历史价格计算当前持仓篮子，而非窗口内的交易）。
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，并说明近似计算的注意事项（“按历史价格计算当前持仓篮子，而非窗口内的交易”），按交易平台列出交易，最后用一句简短的话说明变化的驱动因素。

快速了解“我需要担心吗”

对我的投资组合进行风险检查。调用 get_holdings 和 get_allocations（按 symbol、asset_class、connector）。分别评估：单项持仓集中度（> 40% 为 ALERT）、交易平台集中度（> 70% 为 ALERT）、稳定币储备（< 5% 为 WARN，= 0% 为 ALERT）、预测市场超配（> 15% 为 WARN）。以 Markdown 表格输出。

报税季

我需要报税。调用 get_transactions 获取过去一年的交易（since=365d）。然后调用 get_pnl（include_history=true，method=fifo）。按 symbol 和月份汇总已实现盈亏。标记所有成本基础未知的卖出交易（没有价格的存入 / 转账）——这些信息缺失之处需要我另行调查，请如实指出。

HUF 视图（或 EUR / GBP）

以匈牙利福林显示我的投资组合。调用 get_holdings（currency=HUF）。按价值降序排序。计算 HUF 总额，并告知汇率来源是实时 API 还是静态回退值。

Polymarket 投注回顾

带我了解 Polymarket 持仓。调用 get_polymarket_positions（group_by_event=true）。然后调用 get_pnl（include_history=true），通过 /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 key + secret	✓ 完整	UNIFIED / SPOT / CONTRACT / FUND 账户。只读密钥。
Binance	API key + secret	✓ 资产持仓	现货账户（/api/v3/account）+ 可选的期货钱包/持仓（/fapi/v2/account）。只读密钥（仅启用“Enable Reading”）。稳定币按 $1 计价；非稳定资产通过批量接口 /api/v3/ticker/24hr?type=MINI 计价。未平仓期货仓位会作为单独的资产持仓显示，并在元数据中包含方向、杠杆、盈亏和强平信息。v0.13 中交易历史为 ok([])，暂缓实现。仅支持 binance.com（binance.us 暂缓实现）。
MetaMask / EVM 钱包	Etherscan V2 API key	✓ 完整	一个密钥即可覆盖 Ethereum、Polygon、BSC、Base、Arbitrum、Optimism。余额支持原生代币和内置的常见 ERC-20 代币（USDC、USDT、WETH、WBTC、LINK、DAI）；交易支持原生代币和 ERC-20 转账。可通过 headless-tracker token add ... 添加自定义代币列表。每个账户可添加多个钱包（一个 Etherscan key，多个地址）。免费套餐需要 Etherscan Pro 才能使用 BSC/Base（否则会自动跳过并发出警告）。
Polymarket	代理钱包地址（无需 API key）	✓ 完整	使用公开的 data-api。通过 /trades?user=PROXY 获取持仓和买入/卖出交易历史（最多约 1000 条最新记录）。已结算亏损的持仓（已结算市场中价值为 $0、但 data-api 仍会返回的持仓）会通过基于价值的尘埃阈值（dustThresholdUsd，默认值为 $0.01）过滤。
Solana 钱包	Base58 地址（无需 API key）	✓ 资产持仓	使用公开的 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([])；将在 v0.14 中支持，并可选择启用高级 RPC。
Hyperliquid	EVM 地址（无需 API key 或签名）	✓ 完整	使用公开的 info 端点。永续合约账户的 权益 报告为账户的净美元价值（抵押品 + 未实现盈亏）；未平仓永续合约仓位会作为单独的资产持仓显示，并在元数据中包含带符号的数量、名义价值、未实现盈亏、入场/强平价格和杠杆——其名义价值会被刻意排除在净资产总额之外（否则会高估杠杆账户）。现货余额通过 spotMetaAndAssetCtxs 中的 USDC 交易对计价；USDC = $1，无法计价的代币会按尘埃过滤。交易历史通过近期成交记录获取（userFills，最多 2000 条）。每个账户可添加多个地址。

要添加新的连接器，请实现 src/connectors/types.ts 中的 Connector，并将其添加到 src/mcp/orchestrator.ts 中的 CONNECTOR_FACTORIES。根据现有六个连接器的实现，每个连接器约需 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）。不指定筛选条件时，会查询所有数据。

账户和设置管理（所有凭据写入操作均使用只读 API 密钥，并将其存储在 OS 钥匙串中）：

工具	用途
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 面板（在聊天中呈现的交互式界面）：

工具	用途
render_dashboard	交互式仪表板面板：持仓、盈亏、资产分配、预测市场
render_settings	设置面板：CLI 设置流程的图形界面替代方案

为什么采用本地优先设计

• API 密钥绝不会离开你的设备。 通过 @napi-rs/keyring 将其存储在 OS 钥匙串中。
• 缓存使用本地 SQLite（运行时内置驱动：Node 下为 node:sqlite，Bun 下为 bun:sqlite）。没有服务端、没有 SaaS，也不会发送分析数据。
• 默认不收集遥测数据。 错误报告完全由用户选择启用：只有在你设置了 SENTRY_DSN 时才会执行任何操作；即便如此，也绝不会发送投资组合数据——不包括金额、余额、钱包地址、API 密钥或账户标签，只会发送错误类别、经过清理的消息／堆栈信息，以及发生故障的连接器。详情请参阅 decisions.md（2026-06-06）。
• 从设计上就是只读的。 不会签署交易。该工具所能做的一切都不会导致你损失资金。
• 按连接器设置缓存 TTL（加密钱包为 60s，交易所为 120s，Polymarket 为 30s），既能保持快速响应，又不会对上游 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 或学习命令行，只需向 Claude 提问即可。以下是一些对话示例：

“我持有哪些资产？”

Claude 调用 get_holdings({})，并返回格式化的明细：“你目前在 Bybit 持有 0.5 BTC（约 $30,000）、2 ETH（约 $5,000），MetaMask 钱包中还持有 1 ETH，以及一笔价值 $60 的 2024 年选举 Polymarket 仓位。投资组合总价值：约 $35,060。”

“按事件分组显示我的 Polymarket 投注。”

Claude 调用 get_polymarket_positions({ group_by_event: true })，并生成一张按事件分组的表格，其中包含标题、你持有的 Yes/No 结果仓位、事件总价值，以及每个事件的合计现金盈亏。

“我的资产在加密货币和预测市场之间如何分配？”

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 去重机制也能确保每个连接器最多只会被调用一次。

开发

从源代码构建需要使用 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> 错误处理——对于预期失败（身份验证、速率限制、网络），不会通过抛出异常的方式处理。

常见问题

我的 API 密钥会被发送到其他地方吗？ 不会。它们存储在操作系统的密钥链中，只会发送到对应的上游 API（Bybit 密钥发送到 Bybit 的 API，Etherscan 密钥发送到 Etherscan 的 API）。MCP 服务完全在你的计算机上运行。

Polymarket 显示了我的持仓，但 Claude 看不到。 请确认你使用的是 Polymarket 代理钱包地址，而不是 MetaMask 地址。你可以在 Polymarket 界面的 Settings → Wallet 中找到该地址。如果用错了，请重新运行 setup polymarket。

Bybit 返回 auth_failed。 请确认 API 密钥具有 Wallet Read + Trade Read 权限（无需 Withdraw 权限）。如果你为密钥设置了 IP 白名单，请确保其中包含你计算机当前的公网 IP。

Etherscan 返回 rate_limited。 免费层级的限制是每秒 5 次调用、每天 100k 次调用。每次 MetaMask 刷新在每条链上需要（1 + N 个代币）次调用。如果你有 4 条链 × 7 种常用代币，每次刷新就需要 32 次调用。请错开刷新请求；缓存 TTL（MetaMask 为 60s）是有原因的。

不使用 Claude Desktop 也能用吗？ 可以——任何兼容 MCP 的宿主都能使用（Claude Code、Cursor、Codex、ZED，以及 MCP 支持稳定后的 ChatGPT）。接入方式相同，只需更改要编辑的客户端配置文件。此外还有用于终端查询的 CLI（headless-tracker show holdings/pnl/transactions），完全无需 AI 宿主。

已实现盈亏看起来不对。 对于 Polymarket，默认的 get_pnl 会返回 realizedPnl: null，因为连接器的 cashPnl 字段混合了已实现和未实现盈亏。传入 include_history=true（或在 CLI 中传入 --include-history=true），即可根据你的 /trades 历史记录按 FIFO 计算出准确数值。对于 MetaMask，链上转入的代币没有已知成本基础；include_history=true 会将它们报告为 unknownSalesCount，而不是虚构 $0 成本。

一个 MetaMask 账户可以追踪多个钱包吗？ 可以。v0.8 为 MetaMask 凭据新增了 addresses[]。设置 CLI 仍只会询问一个钱包（向后兼容），但连接器接受地址列表。直接编辑保险库条目，即可在同一账户中添加更多地址，并共用同一个 Etherscan 密钥和链选择。如果有需求，v0.9 计划添加 wallet add CLI 命令。

支持[我喜欢的交易所 / 链 / 市场]吗？ 暂不支持。欢迎提交 issue 或 PR。Connector 接口支持扩展，现有 3 个连接器是参考实现，总计约 600 行代码。

Polymarket 的交易历史呢？ 从 v0.7.1 起已支持：get_transactions 会从公开的 data-api /trades?user=PROXY 端点返回 BUY/SELL 交易，最多返回最近约 1000 笔。data-api 会忽略按时间范围查询的参数，因此 since 筛选由客户端执行；如果某页记录早于截止时间，分页会提前结束。

为什么没有界面？ Claude Desktop、ChatGPT 和 Cursor 都能按需生成比我在 v1 中发布的界面更丰富的仪表板。构建界面会重复 AI 宿主已经做得更好的工作。如果你想要托管的 Web 界面，请参阅 bulltrapp.com。

相关内容

bulltrapp.com — 同一维护者提供的托管式 Web 投资组合追踪器。问题领域相同，呈现形式不同。可以任选其一，也可以同时使用。

许可证

MIT