MCP Hud

MCP HUD

Claude Code状态线的实时MCP提供程序使用情况

显示 食品法典委员会速率限制, Gemini使用量估计，以及 Context7呼叫计数 直接在您的Claude Code状态行中。

[OMC v4.2.15 | ...] | Cx:5h:4%·wk:2%(9) Gm:d:2%·mo:0%(8) C7:39

特性

输出格式

Cx:5h:4%·wk:2%(9)    — Codex: 4% of 5-hour window, 2% of weekly, 9 calls total
Gm:d:2%·mo:0%(8)     — Gemini: 2% of daily limit, 0% of monthly, 8 calls total
C7:39                 — Context7: 39 calls total

安装

快速安装

git clone https://github.com/hyunseok-blue/mcp-hud.git
cd mcp-hud && bash install.sh

手动安装

git clone https://github.com/hyunseok-blue/mcp-hud.git ~/.claude/mcp-hud
chmod +x ~/.claude/mcp-hud/mcp-hud.mjs

增添 ~/.claude/settings.json:

{
  "statusLine": {
    "command": "node ~/.claude/mcp-hud/mcp-hud.mjs"
  }
}

运作原理

┌──────────────┐     ┌───────────────┐     ┌─────────────┐
│  mcp-hud.mjs │────▶│ lib/mcp-scan  │────▶│ .jsonl files │
│  (main HUD)  │     │ (background)  │     │ (transcripts)│
│              │     └───────────────┘     └─────────────┘
│              │     ┌───────────────┐     ┌─────────────┐
│              │────▶│ lib/codex-scan│────▶│codex app-srv│
│              │     │ (background)  │     │ (JSON-RPC)  │
└──────┬───────┘     └───────────────┘     └─────────────┘
       │
       ▼
  ┌──────────┐
  │ OMC HUD? │──yes──▶ Wrap OMC output + append MCP segment
  │          │──no───▶ Standalone: print [MCP] segment
  └──────────┘

背景扫描仪写入 ~/.claude/hud/ 缓存文件，并在缓存过时时延迟生成。HUD从缓存中读取，从不阻塞。

OMC用户与独立用户

当安装了我的claudecode时，HUD会自动包裹OMC HUD。无需额外配置。

配置

环境变量（全部可选）：

需求

• Node.js 18+ （必填）
• 克劳德代码 （必填）
• Codex CLI （可选--启用实时速率限制显示）

  npm i -g @openai/codex

• Gemini CLI （可选——不管怎样，都会从成绩单中跟踪通话）

  npm i -g @google/gemini-cli

数据收集方法

Codex——通过JSON-RPC实现实时速率限制

Codex CLI公开了一个 app-server 它讲JSON-RPC。扫描仪：

1. 生成物 codex app-server 作为一个孩子的过程
2. 发送 initialize （JSON-RPC id:0）到握手
3. 发送 account/rateLimits/read （JSON-RPC id:1）获取实时速率数据
4. 接收结构化响应 primary （5小时窗口）和 secondary （每周窗口）
5. 每个窗口包括 usedPercent 和 windowDurationMins
6. 将结果写入 ~/.claude/hud/codex-usage.json （缓存TTL:5分钟）

这给了 精确 实时使用百分比——无需估算。

Codex app-server                    codex-scan.mjs
      │                                  │
      │◀──── initialize ────────────────│
      │───── {capabilities} ──────────▶ │
      │◀──── rateLimits/read ──────────│
      │───── {primary, secondary} ───▶  │──▶ codex-usage.json

Gemini——根据转录挖掘估算

Gemini CLI具有 无费率限制API.通过扫描Claude Code成绩单估算使用量：

1. 步行全部 .jsonl 文件在 ~/.claude/projects/ （对话记录）
2. 对于每个文件，正则表达式匹配Gemini MCP工具调用： "name":"mcp__*_g__ask_gemini"
3. 对于每个匹配，从同一JSON行中提取时间戳：

- 尝试 "timestamp", "created_at", "ts" 领域 - 支持ISO字符串和纪元毫秒 - 追溯到文件修改日期(stat.mtime)未找到时间戳时

1. 每次呼叫都会收到Buckets today / this month / total
2. 计算已知可用层限制的百分比：

- 日常：1500 RPD（谷歌AI免费版，Gemini 2.5 Pro） - 每月：50000个请求（可配置）

1. 将结果写入 ~/.claude/hud/mcp-counts.json （缓存TTL:2分钟）

~/.claude/projects/**/*.jsonl
      │
      ├── session-abc.jsonl ──▶ regex match ──▶ extract timestamp ──▶ bucket
      ├── session-def.jsonl ──▶ regex match ──▶ extract timestamp ──▶ bucket
      └── ...                                                          │
                                                                       ▼
                                                              mcp-counts.json
                                                              {codex:9, gemini:{today:3,month:8,total:8}, context7:39}

上下文7——累计转录计数

与Gemini相同的转录扫描，但只跟踪总计数（没有速率限制）。比赛： "name":"mcp__*context7*"

为什么使用背景扫描仪？

HUD脚本在每次Claude Code状态行刷新时运行（经常）。每次刷新时扫描转录本或调用Codex API会太慢。相反：

• HUD从以下位置读取 缓存文件 （瞬间，\<1ms）
• 当缓存过时时，将扫描程序作为 分离背景进程
• 扫描仪运行、写入缓存、退出——下一次HUD刷新会获取新数据
• 无阻塞，对Claude Code无延迟影响

文件结构

mcp-hud/
├── mcp-hud.mjs          # Main HUD entry point
├── lib/
│   ├── mcp-scan.mjs     # MCP call counter (daily/monthly for Gemini)
│   └── codex-scan.mjs   # Codex rate limit scanner (JSON-RPC)
├── install.sh            # One-click installer
├── examples/
│   └── settings.json     # Claude Code settings example
├── LICENSE               # MIT
└── README.md

许可证

麻省理工学院