Mcp Claude Usage Guard

io.github.GuardBee由 GitHub 账号 GuardBee 发布v0.1.1更新于 Nov 19, 2026

Detects Claude plan usage that did not come from your own Claude Code: plan meter vs local transcrip

发布方自己的服务:Claude Platform Docs

已验证STDIO仅桌面安全与监控数据与分析

概览

AI 生成的概览

一个 MCP 服务器,通过对比账户套餐用量表与本机记录,判断 Claude 套餐用量是否都来自本机的 Claude Code。

可以做什么
  • 记录套餐用量表读数,与本机用量对比后给出结论:数据不足、无证据、可疑或很可能来自其他来源。
  • 按会话、日期、项目、入口或模型报告本机 Claude Code 的用量,并给出每个会话的峰值上下文大小。
  • 显示 Claude Code 当前登录的账户,以及最近获取的 5 小时和 7 天用量表。
  • 提示本地信号,例如账户切换、使用你登录凭据的 SDK 或脚本入口、远程登录以及后台会话。
适用场景
当 Claude 套餐额度消耗得比预期快,想弄清用量是来自本机的 Claude Code 还是账户上的其他来源时适用。也适合按项目、模型或入口回顾自己的本地用量情况。
运行要求
以 stdio 方式在本机运行,通常通过 npx 使用已发布的 npm 包。需要读取 Claude Code 的本地文件,包括 Claude 配置文件中缓存的用量表和项目目录下的记录;可用 CLAUDE_CONFIG_DIR 和 GUARDBEE_USAGE_GUARD_DIR 环境变量更改路径。需要多次读数,因此要反复运行或安排定时快照才能得出结论。
安装前请注意
会读取本地 Claude Code 配置与对话记录文件,并把用量表读数存入本地快照文件。说明称遥测默认关闭,但引用了单独的遥测包。结论基于启发式判断:只能看到本机,其他设备只会表现为无法解释的用量,缓存的用量表字段属于内部字段,可能变化。你自己在 claude.ai、桌面端或手机端的对话也会被算作无法解释的用量。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Mcp Claude Usage Guard,将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only,通过 STDIO。 STDIO 服务会启动本地进程,因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

@guardbee/mcp-claude-usage-guard

🇬🇧 English | 🇹🇷 Türkçe | 🇨🇳 中文 | 🇯🇵 日本語 | 🇰🇷 한국어 | 🇧🇷 Português | 🇪🇸 Español | 🇩🇪 Deutsch

[npm version] [License: MIT]

An MCP server that answers one question: is all of my Claude plan usage coming from me?

Your plan's 5-hour and 7-day limits are shared by everything signed in to the account: Claude Code on every machine, claude.ai, the desktop and mobile apps, and any script that borrowed your login. When the limits run out faster than expected, this server compares the account-wide plan meter with what Claude Code on this machine actually spent, and points at the gap.

Telemetry is off by default. See @guardbee/mcp-telemetry. Nothing else leaves the machine: the server only reads local files.

plan meter (whole account, from Claude Code's /usage cache)        │          ┌──────────────────────────────────────────┐        ├─ rose ──►│ explained by this machine's transcripts? │── yes ─► ✅ no evidence        │          └──────────────────────────────────────────┘        │                              │ no        │                              ▼        │                 🚨 usage from somewhere else        │        └─ plus local signals: account switch · SDK/script use of your login · remote logins · background sessions

Tools

ToolWhat it does
detect_foreign_usageRecords a plan reading, compares the meter's movement between readings with this machine's usage, and reports a verdict: insufficient-data, no-evidence, suspicious or likely-other-usage.
usage_reportThis machine's Claude Code usage from local transcripts, by session, day, project, entrypoint or model, with each session's peak context size.
account_statusWhich account Claude Code is signed in to, and the 5-hour / 7-day meters it last fetched.

How detection works

  1. Plan readings. Claude Code caches the meters it shows in /usage in ~/.claude.json. Each call stores that reading in ~/.guardbee/claude-usage-guard/snapshots.jsonl.
  2. Local spend. Transcripts under ~/.claude/projects give every model call this machine made. Claude Code writes one line per content block and repeats the response's usage on each, so calls are counted once per message id (summing every line overstates usage 2-3x).
  3. Weighting. Limits follow cost, not raw tokens: input + 1.25×cache write + 0.1×cache read + 5×output, scaled down for Sonnet and Haiku.
  4. Comparison. For each pair of readings inside the same limit window:
    • meter rose 3+ points while this machine was idle → flagged without any calibration;
    • otherwise, once three busy intervals have taught it how many weighted tokens one point costs, an interval where this machine explains less than half of the rise is flagged.
  5. Local signals. A plan reading fetched for another account than the signed-in one, SDK or script entrypoints (sdk-ts, sdk-py, …) spending your login, who showing remote logins, non-interactive Claude Code processes.

"Usage from somewhere else" is not necessarily another person: your own claude.ai, desktop or mobile chats share the same limits. The report says so.

Getting enough readings

Claude Code refreshes the cached meters when it fetches /usage. One reading is not enough; run detect a few times over a working day, or schedule the snapshot command:

bash
# every 30 minutes*/30 * * * * npx -y @guardbee/mcp-claude-usage-guard snapshot

Install

bash
claude mcp add claude-usage-guard -- npx -y @guardbee/mcp-claude-usage-guard

CLI:

bash
npx @guardbee/mcp-claude-usage-guard detect            # verdict + signals (exit 2 on likely-other-usage)npx @guardbee/mcp-claude-usage-guard report --hours 168 --by entrypointnpx @guardbee/mcp-claude-usage-guard snapshot

CLAUDE_CONFIG_DIR is honoured. GUARDBEE_USAGE_GUARD_DIR moves the snapshot store.

Limitations

  • Only this machine's Claude Code is visible. Another device appears as unexplained plan usage, not by name.
  • cachedUsageUtilization is an internal Claude Code field. If it disappears or changes shape, the server falls back to local signals only and says so.
  • Meters are whole percentages, so one point of movement is treated as rounding.
  • Model weights are approximate relative prices.

Related

@guardbee/mcp-token-optimizer finds what is burning tokens on this machine and stops it.

来源:packages/claude-usage-guard/README.md,提交 e039d1a

工具

0
SourceWeft 尚未在沙箱中启动过该软件包,因此其工具未知。

版本历史

1
  1. v0.1.1最新Nov 19, 2026

评分

已满足适用检查项的 50%

该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分

    请保持端点能够响应 MCP 握手;SourceWeft 每 30 天探测一次。

  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头,或保持端点能够响应探测,以便判定其认证方式。

  • 已列出工具15 分

    请让服务器在无凭据时响应 tools/list,或发布可在沙箱中无凭据启动的软件包。

  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分

其他 Claude 集成