Claude Code MCP Server

Claude plan usage

claude_usage

Read-onlyIdempotent

Reports Claude plan usage allowance by session and weekly windows, including percent used, reset time, severity, and credit spend, so agents can check limits before starting or continuing sessions.

Instructions

Report how much of the Claude plan's usage allowance is used: each window (the rolling session window, weekly windows, model- or surface-scoped ones) with its percent, reset time and severity, plus usage-credit spend. Runs print-mode claude -p --restricted -- /usage, a local command that makes no model call and costs nothing; readings are reused for 60 s unless refresh is true. When CLAUDE_MCP_USAGE_STOP_PERCENT is set, blocked_by names the window that makes create and claude_run_local fail with USAGE_LIMIT_NEAR. windows is null when the CLI can't read plan usage.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "claude_usage"
  }
}

Input Schema

Name	Required	Description	Default
`refresh`	No	Read usage now instead of reusing a reading up to 60 s old.

Output Schema

Name	Required	Description
`cli`	Yes	exit_code and the tail of stderr. stdout is empty when the report was read.
`args`	Yes
`cached`	Yes	True when this reading was reused from an earlier call within 60 s.
`parsed`	Yes	True when the CLI's usage report was read.
`windows`	Yes	Usage per window. Null when the CLI can't read the plan's usage (for example, API-key auth).
`blocked_by`	Yes	The session or weekly_all window at or above stop_percent, which makes new work fail with USAGE_LIMIT_NEAR.
`checked_at`	Yes	When this reading was taken (ISO 8601).
`extra_usage`	Yes	Usage-credit spend, when the plan has usage credits.
`stop_percent`	Yes	CLAUDE_MCP_USAGE_STOP_PERCENT, or null when unset.

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.1.3Nov 6, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnly/idempotent annotations, it discloses the execution mechanism (local print-mode CLI, no model call, zero cost), the 60 s cache and how `refresh` overrides it, the env-var-driven USAGE_LIMIT_NEAR gating behavior, and the null-windows failure mode. This is exactly the kind of side-effect and cost disclosure an agent needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose, then behavior, then failure semantics. It is dense but essentially waste-free; the parenthetical enumerating window types is the only slightly padded phrase, and it carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Even though an output schema exists, the description goes further and explains the shape of `windows`, the meaning of `blocked_by`, and the null-windows edge case. Combined with cost, caching, and gating behavior, an agent has everything needed to call and interpret this tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single `refresh` parameter is already documented, so the baseline is 3. The description adds real meaning by pairing `refresh` with the 60 s reuse window and the reason to force a fresh read, which tells the agent when the extra cost is justified.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Report how much of the Claude plan's usage allowance is used,' then enumerates what is reported (windows with percent, reset time, severity, plus usage-credit spend). This is clearly distinguishable from siblings like claude_auth_status or claude_run_local, which do not report allowance consumption.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage context is strongly implied: the tool feeds pre-flight checks, and the description explains that `blocked_by` names the window that makes claude_create_cloud_session and claude_run_local fail with USAGE_LIMIT_NEAR. It stops short of an explicit 'call this before X' instruction or naming when a caller should skip it, so it is clear but not fully prescriptive.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server