The claude-usage-mcp server monitors your Claude subscription usage and provides forecasts and velocity recommendations — reusing your existing Claude Code OAuth session with no API key required.
get_usage: Retrieve current utilization percentages, reset times, remaining hours, projected end utilization, and velocity recommendations for all windows (5-hour, weekly, and weekly-Opus) in a single call.
get_velocity: Query the velocity recommendation for a specific window (5h, weekly, or weekly_opus) — a score of 100% means maintain current pace, <100% means throttle, >100% means you have headroom (capped at 120%).
Forecast quota exhaustion: See when you'd hit 100% utilization at your current pace (exhaustAt timestamp).
No API key needed: Securely reuses the OAuth session already stored by Claude Code.
Optional webhook alerts: Configure HTTP webhooks (e.g., Slack, Discord) to be notified when any usage window crosses a defined utilization threshold, with customizable cooldowns and payload fields.
Click on "Install 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 current usage?"
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.
A tiny MCP server that reports your Claude
subscription usage — the 5-hour and weekly limit windows — with a forecast
and a velocity recommendation. No API key required: it reuses the OAuth
session that Claude Code already stores on your machine, exactly like Claude
Code's own /usage command.
Reads Claude Code's OAuth credentials from ~/.claude/.credentials.json
(or the macOS Keychain item Claude Code-credentials), refreshing the
access token when needed.
Calls the undocumented usage endpoint
GET https://api.anthropic.com/api/oauth/usage with
Authorization: Bearer <token> and anthropic-beta: oauth-2025-04-20.
The response contains five_hour, seven_day and seven_day_opus, each
with utilization (0–100) and resets_at.
Because Anthropic's edge fingerprints the TLS handshake and rejects Node's
fetch with 403 "Request not allowed", the server tries fetch first and
falls back to the system curl binary (which is accepted). curl ships
with Windows 10+, macOS and Linux. Set CLAUDE_USAGE_FORCE_CURL=1 to skip
straight to curl.
You must be signed in via Claude Code (
claude) for this to work.
Related MCP server: Token Analyzer MCP
get_usageNo arguments. Returns every available window with:
utilization, resetsAt, remainingHours, projectedEndUtilization
(where you'd land at reset at the current pace), exhaustAt (when you'd hit
100% if you will), and velocityRecommendation.
get_velocityArgument window: "5h", "weekly", or "weekly_opus". Returns just the
velocity recommendation and forecast for that one window.
A single number telling you how hard you can push. It compares the sustainable pace (the rate that exactly finishes the quota at reset) to your current average pace:
100% — full speed. At your current pace you land exactly at the limit right when the window resets.
< 100% — the fraction of your current pace you should slow to in order not
to run out early. e.g. 40% = go at roughly 40% of your current speed.
> 100% (capped at 120%) — you have so much headroom you can't burn through the quota at anything like this pace. Go all out.
The 5-hour and weekly windows are evaluated separately, so you get
5h and weekly velocities independently.
Math per window (length L = 5h or 168h, utilization u%, reset at R):
elapsed = now - (R - L)
remaining = R - now
rate = u / elapsed # % per hour
forecast = u / (elapsed / L) # % at reset if pace continues
exhaustAt = now + (100 - u) / rate # only if forecast > 100
velocity = ((100 - u) / remaining) / rate * 100 # clamped to [0, 120]npm install
npm run buildClaude Desktop (claude_desktop_config.json), or any stdio MCP client:
{
"mcpServers": {
"claude-usage": {
"command": "node",
"args": ["/absolute/path/to/claude-usage-mcp/dist/index.js"]
}
}
}Get notified — by any system you choose — when a usage window crosses a
threshold. Disabled by default; opt in by setting CLAUDE_USAGE_WEBHOOK_URL.
Fires on every get_usage call and every dist/cli.js run (so it's only as
frequent as whatever already polls this package), independent of client:
Env var | Default | Meaning |
| unset (disabled) | Where to |
|
| Utilization % that triggers the first alert for a window. |
|
| Minutes between repeat alerts while a window stays above the threshold. Dropping back below clears it, so the next rise alerts immediately. |
| unset | JSON object merged into every payload — e.g. |
Payload (Content-Type: application/json):
{
"event": "claude_usage_threshold",
"window": "5h",
"utilization_pct": 87,
"threshold_pct": 80,
"resets_at": "2026-07-17T14:39:27.672Z",
"remaining_hours": 3,
"velocity_recommendation": 49,
"message": "Claude usage (5h) at 87%, over the 80% threshold. Resets in 3h. throttle hard — ~49% of your current pace."
}The message field is a ready-to-post string — point CLAUDE_USAGE_WEBHOOK_URL
at a Slack/Discord incoming webhook, a custom FastAPI endpoint, another MCP
tool's HTTP bridge, whatever you've got. This package has no opinion about the
receiver; it just POSTs plain JSON and never blocks or fails the caller if the
POST errors.
The usage endpoint is undocumented and can change or disappear without notice — treat it as best-effort.
The server can read your Claude Code OAuth tokens (the same file Claude Code
itself uses). It never sends them anywhere except Anthropic's own endpoints,
and passes the bearer token to curl via a stdin config file so it never
appears in the process list.
Velocity uses the average pace over the elapsed window (one snapshot per call). It's a guide, not a guarantee; a burst right before reset can still overshoot.
MIT
Current Claude subscription usage for every window (5-hour, weekly, weekly-Opus): utilization %, reset time, a forecast of where you'll land at reset, when you'd hit the limit at the current pace, and a velocity recommendation (0-120%; 100 = full speed lands exactly at the limit, <100 = throttle, >100 = headroom to spare). Reuses Claude Code's OAuth session; no API key needed.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the burden. It discloses authentication method (OAuth session reuse) and the data returned (utilization, forecast, etc.). It is a read-only retrieval, though not explicitly stated. The description adds valuable behavioral context beyond what schema alone provides.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that packs a lot of information without being overly verbose. It is well-structured and front-loaded with the core function. Slightly long but still concise given the detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless tool with no output schema, the description provides comprehensive details about the returned data (utilization, forecast, limit, velocity) and authentication. It lacks mention of error conditions but is otherwise complete for typical usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so the schema coverage is 100%. The description adds no parameter info because none exist. A baseline of 4 is appropriate for zero parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies exactly what the tool does: get current Claude subscription usage for every window, including utilization, reset time, forecast, limit hit time, and velocity recommendation. It clearly distinguishes from the sibling tool 'get_velocity' by detailing the broader scope beyond just velocity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states it reuses Claude Code's OAuth session and that no API key is needed, but does not explicitly say when to use this tool vs. alternatives like 'get_velocity'. The context is implied but not explicitly contrasted.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Velocity recommendation (0-120%) for one window. 100% = keep going at full speed and you'll land exactly at the limit at reset; <100% = the fraction of your current pace you should slow to; >100% (capped at 120) = you have so much headroom you can't burn through the quota. window: '5h' (rolling 5-hour), 'weekly' (7-day), or 'weekly_opus'.
| Name | Required | Description | Default |
|---|---|---|---|
| window | Yes | Which limit window to evaluate. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It explains the return value range (0-120%) and interpretation for different values, as well as window options. However, it does not mention if the operation is read-only or any permissions needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a concise single paragraph with three front-loaded sentences. Each sentence adds essential information without wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one parameter with full schema coverage and no output schema, the description covers the core functionality and return interpretation. It lacks details on error handling or default behavior but is largely complete for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant meaning to the single parameter 'window' by explaining each enum value ('5h' as rolling 5-hour, 'weekly' as 7-day, 'weekly_opus') beyond the schema's simple description 'Which limit window to evaluate.'
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns a velocity recommendation for one window, with specific meaning for 100%, <100%, and >100%. It distinguishes from sibling 'get_usage' by focusing on recommendation rather than raw usage.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for getting velocity recommendations for a given window but does not explicitly state when to use it over alternatives or provide exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0get_usageget_velocityThe two tools are mostly distinct: get_usage returns comprehensive usage data for all windows, while get_velocity returns only the velocity recommendation for a single window. However, get_usage already includes velocity recommendations, so an agent might be unclear whether to use get_velocity or extract from get_usage.
Both tools follow a consistent verb_noun pattern (get_usage, get_velocity), making them predictable and easy to understand.
With only 2 tools, the server is on the low side but still reasonable for a focused purpose. The tools cover a narrow domain well without being too sparse.
The server covers the core use case of monitoring Claude usage and velocity recommendations. There are no obvious missing operations for its stated purpose, though it could optionally include a tool for a specific window's full data without velocity.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Anthropic organization usage and cost reporting through an admin API key connected by the user.
OpenAI organization usage and cost reporting through an admin API key connected by the user.
WHOOP recovery, strain, sleep and workouts in Claude via official WHOOP OAuth. Free, open source.
Cookieless dashboard aggregates for Claude and Cursor. No visitor hashes. Starter and Growth.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/NG-Bullseye/claude-usage-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server