AI导哈

实时MCP提供商状态监视器

该工具为Claude Code状态行提供实时MCP提供商（如Codex、Gemini、Context7）的使用情况监控，包括调用次数和速率限制百分比。

  • by hyunseokjeong-madup
  • JavaScript
  • 本地部署
  • 更新于
在 GitHub 查看 hyunseok-blue/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

特性

提供者 显示内容 来源
法典 实时速率限制%（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。扫描仪：

  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)未找到时间戳时
  4. 每次呼叫都会收到Buckets today / this month / total
  5. 计算已知可用层限制的百分比：
    • 日常：1500 RPD（谷歌AI免费版，Gemini 2.5 Pro）
    • 每月：50000个请求（可配置）
  6. 将结果写入 ~/.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

许可证

麻省理工学院

相关 MCP