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 Claude usage and when does it reset?"
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.
An MCP server that reports your real Claude subscription usage — 5-hour
session window, weekly limit, and per-model limits — pulled from the same
endpoint Claude Code's /usage command uses.
macOS or Linux
Node.js 20+
Claude Code logged in on a Pro, Max, or Team plan
This server reads Claude Code's own OAuth access token (from the macOS
Keychain, or ~/.claude/.credentials.json as a fallback). It never asks for
or stores credentials itself.
Related MCP server: Claude Usage MCP Server
Add to your .mcp.json.
Local build:
{
"mcpServers": {
"claude-usage": {
"command": "node",
"args": ["/path/to/claude-usage-mcp/dist/index.js"]
}
}
}Or via npx:
{
"mcpServers": {
"claude-usage": {
"command": "npx",
"args": ["-y", "@anatoly314/claude-usage-mcp"]
}
}
}get_usageTakes no arguments. Returns the current usage snapshot as JSON.
{
"session_5h": { "utilization_percent": 42, "resets_at": "2026-09-01T18:00:00Z" },
"weekly_7d": { "utilization_percent": 61, "resets_at": "2026-09-05T00:00:00Z" },
"model_limits": [
{
"model": "Opus",
"kind": "weekly_scoped",
"utilization_percent": 51,
"resets_at": "2026-09-05T00:00:00Z",
"is_active": true
}
],
"fetched_at": "2026-09-01T15:04:00Z",
"stale": false
}If a fetch fails, the last successful response is served instead with
stale: true and stale_age_seconds set.
This uses an undocumented Anthropic endpoint. It may change or break without notice.
Responses are cached for 120 seconds; after a failed fetch, further requests back off for 60 seconds before retrying, to avoid hammering the API.
Everything stays local — no data leaves your machine except the request to Anthropic's usage endpoint.
Report the current user's Claude subscription usage: 5-hour session window, 7-day weekly limit, and any per-model weekly limits, as utilization percentages with reset timestamps.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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 discloses meaningful behavioral details: specific time windows (5-hour, 7-day), per-model limits, output format (utilization percentages), and reset timestamps. It does not explicitly state read-only behavior, but 'Report' strongly implies a non-mutating operation.
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 well-structured sentence that front-loads the core purpose and then packs in the key details: time windows, per-model limits, and output format. There is no wasted text.
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 read-only reporting tool, the description is largely complete. It specifies the scope, the metrics, the format, and reset timestamps. Some minor ambiguity remains about the exact response structure, but no output schema exists and the description provides sufficient practical detail for an agent to invoke the tool correctly.
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 tool has zero parameters, so the baseline is 4. The description adds useful context about what kind of usage data is returned, but there are no parameter semantics to clarify since none exist.
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 identifies the specific verb 'Report' and the exact resource 'the current user's Claude subscription usage', then enumerates the precise metrics covered: session window, weekly limit, and per-model limits. This is unambiguous and sufficiently detailed for an agent to understand what the tool does.
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 clearly implies this tool should be used when an agent needs to check the current user's Claude subscription usage or limits. There are no siblings to differentiate against, and no exclusion criteria are stated, but the context is clear enough for straightforward invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
With only one tool, there is no possibility of confusion or overlap. The single get_usage tool has a clearly defined purpose and no competitors.
The tool name get_usage follows the standard verb_noun convention. With a single tool there are no mixed conventions or inconsistent styles.
The server's purpose is narrowly scoped to reporting Claude subscription usage. One tool fully covers this function without unnecessary bloat, making the count appropriate.
For a read-only usage reporting server, get_usage provides all necessary information (session window, weekly limit, model limits, reset timestamps). No create, update, or delete operations are relevant to the domain.
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.
Cookieless dashboard aggregates for Claude and Cursor. No visitor hashes. Starter and Growth.
Read-only analytics for Convex apps, queryable via MCP from Claude, Cursor, and other clients.
OpenAI organization usage and cost reporting through an admin API key connected by the user.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/anatoly-lab/claude-usage-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
