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特性
| 提供者 | 显示内容 | 来源 |
|---|---|---|
| 法典 | 实时速率限制%（5小时窗口+每周）+通话次数 | codex app-server JSON-RPC |
| 双子座 | 预计每日%·每月%+总通话次数 | 成绩单扫描与已知免费等级限制 |
| 背景7 | 累计通话次数 | 成绩单扫描 |
输出格式
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用户与独立用户
| OMC已安装 | 独立 | |
|---|---|---|
| 输出 | 附加OMC HUD+MCP段 | [MCP] Cx:... Gm:... C7:... |
| 设置 | 一样 settings.json 条目 | 相同 settings.json 入口 |
| 检测 | 自动检测OMC插件缓存 | 回退到独立 |
当安装了我的claudecode时，HUD会自动包裹OMC HUD。无需额外配置。
配置
环境变量（全部可选）：
| 变量 | 默认值 | 描述 |
|---|---|---|
MCP_HUD_CACHE_DIR | ~/.claude/hud | 缓存文件目录 |
MCP_HUD_CODEX_TTL | 300000 （5分钟） | Codex缓存过期阈值（ms） |
MCP_HUD_MCP_TTL | 120000 （2分钟） | MCP扫描缓存过期阈值（ms） |
MCP_HUD_GEMINI_DAILY_LIMIT | 1500 | Gemini对%calc的每日请求限制 |
MCP_HUD_GEMINI_MONTHLY_LIMIT | 50000 | Gemini每月对%calc的请求限制 |
需求
- 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。扫描仪：
- 生成物
codex app-server作为一个孩子的过程 - 发送
initialize（JSON-RPC id:0）到握手 - 发送
account/rateLimits/read（JSON-RPC id:1）获取实时速率数据 - 接收结构化响应
primary（5小时窗口）和secondary（每周窗口） - 每个窗口包括
usedPercent和windowDurationMins - 将结果写入
~/.claude/hud/codex-usage.json（缓存TTL:5分钟）
这给了 精确 实时使用百分比——无需估算。
Codex app-server codex-scan.mjs
│ │
│◀──── initialize ────────────────│
│───── {capabilities} ──────────▶ │
│◀──── rateLimits/read ──────────│
│───── {primary, secondary} ───▶ │──▶ codex-usage.jsonGemini——根据转录挖掘估算
Gemini CLI具有 无费率限制API.通过扫描Claude Code成绩单估算使用量：
- 步行全部
.jsonl文件在~/.claude/projects/（对话记录） - 对于每个文件，正则表达式匹配Gemini MCP工具调用：
"name":"mcp__*_g__ask_gemini" - 对于每个匹配，从同一JSON行中提取时间戳：
- 尝试 "timestamp", "created_at", "ts" 领域 - 支持ISO字符串和纪元毫秒 - 追溯到文件修改日期(stat.mtime)未找到时间戳时
- 每次呼叫都会收到Buckets
today/this month/total - 计算已知可用层限制的百分比：
- 日常：1500 RPD（谷歌AI免费版，Gemini 2.5 Pro） - 每月：50000个请求（可配置）
- 将结果写入
~/.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许可证
麻省理工学院