Mcp Claude Usage Guard

io.github.GuardBeePublished by GitHub account GuardBeev0.1.1Updated Nov 19, 2026

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

The publisher's own server: Claude Platform Docs

VerifiedSTDIODesktop onlySecurity & MonitoringData & Analytics

Overview

AI-generated overview

An MCP server that checks whether all of your Claude plan usage came from Claude Code on this machine, by comparing the account plan meter with local…

What you can do
  • Record plan meter readings and compare them with this machine's usage to get a verdict: insufficient data, no evidence, suspicious, or likely other usage.
  • Report this machine's Claude Code usage from local transcripts by session, day, project, entrypoint or model, including each session's peak context size.
  • Show which account Claude Code is signed in to and the last fetched 5-hour and 7-day meters.
  • Surface local signals such as account switches, SDK or script entrypoints using your login, remote logins and background sessions.
When to use it
Useful when your Claude plan limits run out faster than expected and you want to know whether the usage came from your own Claude Code on this machine or from elsewhere on the account. Also handy for reviewing your own local usage patterns by project, model or entrypoint.
Requirements
Runs locally over stdio, typically via npx with the published npm package. Reads Claude Code's local files, including the cached meters in the Claude config file and transcripts under the projects directory; the CLAUDE_CONFIG_DIR and GUARDBEE_USAGE_GUARD_DIR environment variables can relocate these paths. Needs several readings over time, so repeated runs or a scheduled snapshot are required for a verdict.
Before you install
Reads local Claude Code configuration and transcript files, and stores plan readings in a local snapshot file. Telemetry is described as off by default, but a separate telemetry package is referenced. Verdicts are heuristic: only this machine is visible, another device shows up as unexplained usage, and the cached meter field is internal and may change. Usage from your own claude.ai, desktop or mobile chats also counts as unexplained.

Installation

In SourceWeft

  1. Open Mcp Claude Usage Guard in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

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.

Source: packages/claude-usage-guard/README.md at commit e039d1a

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.1LatestNov 19, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

Other Claude integrations