Skip to content
MCP server

MCP Claude Usage Guard

MCP server that checks whether Claude plan usage is coming from your own Claude Code

Runs locally
Install
Pricing
Open source
Platforms
CLI, macOS, Linux
Runs
Locally
Version
0.1.1
Listing updated
today

Similar MCP servers

About MCP Claude Usage Guard

MCP Claude Usage Guard is an open-source MCP server for developer tools. It runs locally on your machine and is started by your AI client.

Claude plan limits are shared by every session signed in to the same account, so a meter can drain faster than your own work would explain. The README says this server compares the account-wide plan meter with the usage recorded in local Claude Code transcripts, then points to any gap it cannot account for.

It works by storing timestamped plan readings in a local snapshot file and weighting transcript token counts by cost, since limits follow cost rather than raw tokens. Between two readings inside the same limit window, a meter rise that this machine does not explain is flagged. It also looks at local signals such as SDK or script entrypoints, remote logins shown by who, and non-interactive Claude Code processes.

The README is clear that a flagged gap is not proof of another person, because the user's own claude.ai, desktop or mobile chats draw from the same limits. It is aimed at developers and heavy Claude users who want to diagnose unexpected limit consumption. Telemetry is off by default and the server only reads local files.

Install

Run in a terminal

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

Add to claude_desktop_config.json

{
  "mcpServers": {
    "mcp-claude-usage-guard": {
      "command": "npx",
      "args": [
        "-y",
        "@guardbee/mcp-claude-usage-guard"
      ]
    }
  }
}
Install in CursorOpens Cursor, which asks you to confirm. Or add it by hand:

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "mcp-claude-usage-guard": {
      "command": "npx",
      "args": [
        "-y",
        "@guardbee/mcp-claude-usage-guard"
      ]
    }
  }
}
Install in VS CodeOpens VS Code, which asks you to confirm. Or add it by hand:

Add to .vscode/mcp.json

{
  "servers": {
    "mcp-claude-usage-guard": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@guardbee/mcp-claude-usage-guard"
      ]
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "mcp-claude-usage-guard": {
      "command": "npx",
      "args": [
        "-y",
        "@guardbee/mcp-claude-usage-guard"
      ]
    }
  }
}

Add to your client's MCP settings (most use this shape)

{
  "mcpServers": {
    "mcp-claude-usage-guard": {
      "command": "npx",
      "args": [
        "-y",
        "@guardbee/mcp-claude-usage-guard"
      ]
    }
  }
}

Using several servers? Build one config file with the MCP config generator.

Tools this server provides (3)

Taken from the project documentation; the running server may differ.

detect_foreign_usage
Records a plan reading, compares meter movement with this machine's usage, and reports a verdict.
usage_report
Shows this machine's Claude Code usage from local transcripts by session, day, project, entrypoint or model.
account_status
Shows the signed-in Claude Code account and the 5-hour and 7-day meters it last fetched.

What it does

Plan meter comparison
Stores plan readings and compares meter movement against this machine's transcript usage.
Verdict reporting
Returns a verdict of insufficient-data, no-evidence, suspicious or likely-other-usage.
Local usage report
Breaks down Claude Code usage by session, day, project, entrypoint or model.
Account status check
Shows which account Claude Code is signed in to and the last fetched 5-hour and 7-day meters.
Local-only data reads
Reads local files only, with telemetry off by default.
Scheduled snapshots
Can run the snapshot command on a cron schedule to gather readings over time.

Good for

  • Diagnosing why Claude plan limits run out faster than expected
  • Checking whether scripts or SDK calls are spending a personal Claude login
  • Reviewing Claude Code usage by project, model or entrypoint over a week
  • Collecting plan readings across a working day to improve detection

Pricing

Open source

Free npm package; no paid plan mentioned.

MCP Claude Usage Guard FAQ

Does it send data off the machine?

The README says telemetry is off by default and the server only reads local files, with nothing else leaving the machine.

How do I install it?

The README gives the command claude mcp add claude-usage-guard -- npx -y @guardbee/mcp-claude-usage-guard, and also offers a CLI with detect, report and snapshot commands.

Can it identify which device used the extra usage?

No. The README says another device appears as unexplained plan usage, not by name.

Why might a flagged result not mean another person?

The README notes that the user's own claude.ai, desktop or mobile chats share the same limits.

Is MCP Claude Usage Guard free?

Yes. MCP Claude Usage Guard is open source, so you can use and self-host it for free.

How do I add MCP Claude Usage Guard to Claude Code?

Run this command in your terminal: claude mcp add mcp-claude-usage-guard -- npx -y @guardbee/mcp-claude-usage-guard

What are the best alternatives to MCP Claude Usage Guard?

The closest alternatives to MCP Claude Usage Guard are Claude Usage, MCP Token Optimizer, lake-meter, Traced Claude Format Guard and Actvt.

Where this comes from

  • Description: written from the project's README and its MCP Registry entry.
  • Install steps: from the official MCP Registry entry.

How AIPoweredBot checks servers