# MCP Claude Usage Guard

> MCP Claude Usage Guard is an open-source MCP server for developer tools. MCP server that checks whether Claude plan usage is coming from your own Claude Code. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, macOS, Linux, Windows
- **Repository:** https://github.com/guardbee/guardbee-mcp/tree/HEAD/packages/claude-usage-guard
- **MCP Registry name:** io.github.GuardBee/mcp-claude-usage-guard
- **Categories:** [developer tools](https://ai-powered.com/categories/developer-tools)
- **Listing updated:** 2026-11-19

## About

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.

## Features

- **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

## Install

### Claude Code (Terminal)

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

### Claude Desktop (claude_desktop_config.json)

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

### Cursor (~/.cursor/mcp.json)

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

### VS Code (.vscode/mcp.json)

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

### Windsurf (~/.codeium/windsurf/mcp_config.json)

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

### Other clients (your client's MCP settings (most use this shape))

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

## Tools

- `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.

## 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.

## Alternatives

- [Claude Usage](https://ai-powered.com/mcp/claude-usage): Claude Usage is an open-source MCP server for ai models and llm tooling.
- [MCP Token Optimizer](https://ai-powered.com/mcp/mcp-token-optimizer-2): MCP Token Optimizer is an open-source MCP server for developer tools.
- [lake-meter](https://ai-powered.com/mcp/lake-meter): lake-meter is an open-source MCP server for developer tools.
- [Traced Claude Format Guard](https://ai-powered.com/mcp/traced-claude-format-guard): Traced Claude Format Guard is an MCP server for ai models and llm tooling.
- [Actvt](https://ai-powered.com/mcp/actvt): Actvt is a freemium MCP server for developer tools.
- [MCP](https://ai-powered.com/mcp/mcp-mwenkagg): MCP is a freemium MCP server for developer tools.
- [Charlotte](https://ai-powered.com/mcp/charlotte): Charlotte is an MCP server for developer tools.
- [Budgethelm](https://ai-powered.com/mcp/budgethelm): Budgethelm is a freemium MCP server for developer tools.

---
Source: https://ai-powered.com/mcp/mcp-claude-usage-guard
