Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@claude-usage-mcp What's my usage right now?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Claude Code shows you your usage in /usage: how much of the 5-hour session and the weekly
limit you've burned. The model itself can't see any of it. Ask it to "keep this project under 20%
of my week" and it has to guess.
claude-usage-mcp gives the AI the same numbers you see, as tools it can call, plus a simple
budget it can check between steps.
Related MCP server: llm-quota-mcp
Needs Node 18+ and Claude Code logged in with a Pro or Max plan.
git clone https://github.com/AlphaSaleAidan/claude-usage-mcp ~/claude-usage-mcp
claude mcp add -s user claude-usage -- node ~/claude-usage-mcp/server.mjsRestart Claude Code and try:
"What's my usage right now?"
"Budget 20% of my weekly on the website rebuild."
Tool | What it does |
| Session (5-hour) %, weekly %, per-model weekly caps, and time until each resets |
| Start a budget for a project: the max % of your weekly limit it may use |
| How much of the budget is used and left, with a status: |
| Delete a budget |
get_usage returns:
{
"session_pct": 38,
"session_resets_in": "2h 14m",
"weekly_pct": 62,
"weekly_resets_in": "3d 9h",
"weekly_resets_at": "2026-10-04T09:59:59+00:00",
"weekly_fable_pct": 12
}budget_check returns:
{
"project": "website-rebuild",
"budget_pct": 20,
"used_pct": 14,
"remaining_pct": 6,
"status": "OK"
}Budgets carry over the weekly reset (usage from before the reset still counts) and live in
~/.claude/usage-budgets.json.
Add this to your CLAUDE.md:
When a usage budget is active for the current project, call budget_check between major
steps and stop to tell me when it says LOW or OVER_BUDGET.See your limits at the bottom of Claude Code at all times. Add this to ~/.claude/settings.json:
"statusLine": {
"type": "command",
"command": "node ~/claude-usage-mcp/server.mjs --statusline"
}session 38% (2h 14m) · week 62% (3d 9h) · website-rebuild 14/20%Any number turns yellow at 75% and red at 90% of its limit.
node ~/claude-usage-mcp/server.mjs # prints usage + all budgets as JSONIt reads your existing Claude Code login (~/.claude/.credentials.json, or the macOS Keychain)
and calls the same endpoint /usage uses. Your token is only ever sent to api.anthropic.com.
Results are cached for 60 seconds in ~/.claude/usage-cache.json, so the status bar never hammers the API.
Budgets are account-wide. A budget measures how much your weekly % went up since it started. Other Claude sessions running at the same time count against it too.
Unofficial endpoint. Anthropic doesn't document it, so it may change. Open an issue if it breaks.
Expired login? Run any claude command once, then retry.
Overrides: CLAUDE_CONFIG_DIR, CLAUDE_OAUTH_TOKEN, CLAUDE_USAGE_BUDGETS.
Not affiliated with Anthropic.
MIT © 2026 Aidan Pierce
This server cannot be deployed
Agentic workflow budget approvals with usage receipts.
Budget & cost control for AI agents — per-agent spend caps + rate limits before each call.
Meter, cap, and block AI agent spend before the provider is charged.
Anthropic organization usage and cost reporting through an admin API key connected by the user.