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 整合