How do I use claudeusage-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@claudeusage-mcp show my current usage and when my limits 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.

claudeusage-mcp

by Orellius-Archive

Overview Schema Related Servers Score Discussions

TypeScript

Local

orellius-claudetracker

An MCP server that gives you real-time visibility into your Claude Pro/Max subscription usage — directly inside Claude Code.

No API keys. No scraping. No browser automation. It reads the OAuth token that Claude Code already stores on your machine and calls Anthropic's usage endpoint to get the exact same data shown on claude.ai/settings/usage.

What it shows

Metric	Description
Current Session	5-hour burst window utilization with reset countdown
Weekly Usage - All Models	7-day rolling limit across all models
Weekly Usage - Opus Only	7-day Opus-specific usage (Max plans)
Weekly Usage - Sonnet Only	7-day Sonnet-specific usage
Extra Usage	Enabled/disabled, monthly limit, credits used

MCP tool output (`get_usage`)

=== Claude Plan Usage ===

Current Session (5-hour window)
  ████████░░░░░░░░░░░░  37%
  Resets in 2h 14m (Sat Mar 22 07:59PM)

Weekly Usage - All Models (7-day) [HIGH]
  ██████████████████░░  89%
  Resets in 4d 3h (Wed Mar 26 05:00PM)

Weekly Usage - Opus Only
  N/A (not on your plan)

Weekly Usage - Sonnet Only
  ░░░░░░░░░░░░░░░░░░░░  1%
  Resets in 4d 3h (Wed Mar 26 08:59PM)

Extra Usage: Disabled

--- Color Grading ---
0-49% = GREEN (safe)  |  50-79% = ORANGE (moderate)  |  80-99% = RED (high)  |  100% = RATE LIMITED

(live data)

Rate-limited state

When any metric hits 100%, the output changes to show reset date and time:

Weekly Usage - All Models (7-day) [RATE LIMITED]
  XXXXXXXXXXXXXXXXXXXX  100%
  Resets in 1d (Mon Mar 24 05:00PM)

Statusline output

The included statusline script adds a third line to your Claude Code status bar with progress bars and color coding:

  Usage: Session █░░░░░░░░░ 13% | Weekly █████████░ 94% | Sonnet █░░░░░░░░░ 8%

When rate-limited:

  Usage: Session: RATE LIMITED, Resets in: 3h 37m (Sun Mar 22 07:59PM) | Weekly: RATE LIMITED, Resets in: 1d (Mon Mar 23 05:00PM)

Color grading

Range	Color	Status
0-49%	Green	Safe
50-79%	Orange	Moderate
80-99%	Red	High
100%	Red + text	RATE LIMITED with reset datetime

Tools

Tool	Purpose
`get_usage`	Full dashboard — session, weekly, per-model, extra usage with progress bars
`get_session_usage`	Current 5-hour session window only
`get_weekly_limits`	7-day limits with per-model breakdown (All, Opus, Sonnet)
`check_rate_status`	Am I about to be rate-limited? Returns LOW / MODERATE / HIGH / RATE LIMITED

Requirements

Node.js >= 18
Claude Code logged in with a Pro or Max subscription
macOS or Linux (reads credentials from Keychain or ~/.claude/.credentials.json)

Installation

Option 1: `claude mcp add` (recommended)

git clone https://github.com/OrelliusAI/orellius-claudetracker.git
cd orellius-claudetracker
npm install && npm run build

claude mcp add orellius-claudetracker -- node $(pwd)/dist/index.js

Restart Claude Code. Then ask "what's my usage?" or type /usage.

Option 2: Manual config

git clone https://github.com/OrelliusAI/orellius-claudetracker.git
cd orellius-claudetracker
npm install && npm run build

Add to your MCP config (.claude.json or project .mcp.json):

{
  "mcpServers": {
    "orellius-claudetracker": {
      "command": "node",
      "args": ["/absolute/path/to/orellius-claudetracker/dist/index.js"]
    }
  }
}

Optional: Statusline integration

Add usage data to your Claude Code statusline (always visible at the bottom):

# If you DON'T have a statusline yet:
cp statusline.sh ~/.claude/usage-statusline.sh
chmod +x ~/.claude/usage-statusline.sh

Then set in ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "bash ~/.claude/usage-statusline.sh"
  }
}

If you already have a statusline, use statusline-combined.sh instead — it pipes your existing statusline and appends the usage line.

How it works

Claude Code (your session)
    |
    |-- Reads OAuth token from:
    |   |-- macOS Keychain ("Claude Code-credentials")
    |   +-- ~/.claude/.credentials.json (Linux/WSL)
    |
    |-- Calls: GET https://api.anthropic.com/api/oauth/usage
    |   Headers: Authorization: Bearer <your-oauth-token>
    |            anthropic-beta: oauth-2025-04-20
    |
    |-- Caches response for 60 seconds
    |   +-- On 429 (rate limit): serves stale cache
    |
    +-- Returns formatted usage data via MCP tools

Zero configuration. The OAuth token is created automatically when you sign into Claude Code with your Pro/Max subscription. No API keys, no environment variables, no .env files.

Authentication

This server uses the same OAuth token that Claude Code creates when you log in:

Platform	Location
macOS	Keychain (service: `Claude Code-credentials`)
Linux / WSL	`~/.claude/.credentials.json`

Required OAuth scopes: user:inference, user:profile

Token issues?

If the server reports authentication errors:

Your token may be expired — restart Claude Code to trigger a fresh OAuth login
Token created via claude setup-token or /login may have wrong scopes — delete credentials and restart Claude Code

Do NOT use API keys (sk-ant-api...). This server is for Pro/Max subscribers, not API users.

Rate limiting

Anthropic's /api/oauth/usage endpoint is aggressively rate-limited. This server handles it:

Caching — responses cached for 60 seconds (MCP) or 120 seconds (statusline)
Stale fallback — on 429, the last successful response is served
Graceful errors — clear messages when the API is unavailable

Who is this for?

Claude Pro and Max subscribers who use Claude Code and want to see their plan usage without opening a browser. This is not for API users — if you have an API key (sk-ant-api...), use the Usage and Cost API instead.

License

MIT

Available Tools

4 tools

check_rate_statusA

Check if you are close to being rate limited. Returns a clear status: LOW, MODERATE, or HIGH usage with actionable advice.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.2/5.0

Behavior3/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It describes the tool's behavior by stating it returns a status with actionable advice, which is useful. However, it does not disclose other traits such as whether it requires authentication, has rate limits itself, or provides real-time data, leaving some behavioral aspects unclear.

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

Conciseness5/5

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

The description is a single, efficient sentence that front-loads the purpose and key details without any wasted words. It is appropriately sized for a simple tool with no parameters, making it highly concise and well-structured.

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

Completeness4/5

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

Given the tool's simplicity (0 parameters, no output schema, no annotations), the description is mostly complete by explaining the purpose and return values. However, it lacks details on behavioral traits like authentication needs or data freshness, which could enhance completeness for a rate-limiting tool. Without an output schema, it adequately describes returns but could be more thorough.

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?

The tool has 0 parameters with 100% schema description coverage, so the schema already fully documents the lack of inputs. The description adds no parameter information, which is appropriate. Baseline is 4 for 0 parameters, as no additional semantics are needed beyond what the schema provides.

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?

The description clearly states the tool's purpose with specific verbs ('Check') and resource ('rate limited'), and distinguishes it from siblings by focusing on status assessment rather than usage retrieval. It specifies the exact return values (LOW, MODERATE, HIGH) and includes actionable advice, making the purpose highly specific and differentiated.

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?

The description implies usage context ('close to being rate limited') and suggests when to use it, but does not explicitly state when not to use it or name alternatives among the sibling tools. It provides clear context for usage but lacks explicit exclusions or comparisons to tools like get_session_usage or get_weekly_limits.

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

get_session_usageA

Get your current 5-hour session usage window — how much of your burst limit you have used and when it resets.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.1/5.0

Behavior3/5

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

With no annotations provided, the description carries the full burden. It discloses the tool's purpose and output semantics (burst limit usage and reset time) but lacks details on behavioral traits like error conditions, authentication needs, or rate limits. It doesn't contradict annotations, but offers only basic operational context.

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

Conciseness5/5

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

The description is a single, efficient sentence that front-loads the purpose and includes all necessary details without waste. Every word earns its place, making it highly concise and well-structured for quick understanding.

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

Completeness3/5

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

Given the tool's simplicity (0 parameters, no annotations, no output schema), the description is adequate but minimal. It explains what the tool does but lacks context on output format, error handling, or integration with sibling tools. For a read-only tool with no structured data, it meets basic needs but could be more comprehensive.

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?

The tool has 0 parameters with 100% schema description coverage, so no parameter documentation is needed. The description appropriately omits parameter details, focusing on the tool's purpose. A baseline of 4 is applied since it compensates well for the lack of parameters by clarifying what the tool returns.

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?

The description clearly states the specific action ('Get'), resource ('your current 5-hour session usage window'), and scope ('how much of your burst limit you have used and when it resets'). It distinguishes from siblings by focusing on session-specific burst limits rather than rate status, general usage, or weekly limits.

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?

The description implies usage context for monitoring burst limit consumption and reset timing, which helps differentiate from siblings like 'get_weekly_limits' or 'check_rate_status'. However, it lacks explicit guidance on when to use this tool versus alternatives or any prerequisites, preventing a perfect score.

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

get_usageB

Get a full dashboard of your Claude Pro/Max subscription usage: session limits, weekly limits (all models, Opus, Sonnet), and extra usage credits.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

B3.4/5.0

Behavior2/5

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

With no annotations provided, the description carries full burden but only states what data is returned, not behavioral traits like authentication requirements, rate limits, freshness of data, or error conditions. It doesn't disclose whether this is a read-only operation (implied but not stated) or any system impacts.

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

Conciseness5/5

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

Single sentence efficiently conveys the tool's purpose and scope with zero wasted words. Front-loaded with the core action ('Get a full dashboard') followed by specific details about what's included.

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

Completeness3/5

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

For a zero-parameter tool with no output schema, the description adequately covers what data is returned but lacks information about authentication, rate limits, or error handling. Given the absence of annotations and output schema, more behavioral context would be helpful for an agent.

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?

With 0 parameters and 100% schema description coverage, the baseline is 4. The description appropriately doesn't discuss parameters since none exist, focusing instead on the tool's purpose and output scope.

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

Purpose4/5

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

The description clearly states what the tool does ('Get a full dashboard of your Claude Pro/Max subscription usage') with specific resources identified (session limits, weekly limits, extra usage credits). It distinguishes from siblings by mentioning comprehensive dashboard vs. specific components, though not explicitly naming alternatives.

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

Usage Guidelines3/5

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

The description implies usage context (checking subscription usage) but doesn't provide explicit guidance on when to use this vs. sibling tools like get_session_usage or get_weekly_limits. No when-not-to-use or prerequisite information is included.

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

get_weekly_limitsB

Get your 7-day weekly usage limits broken down by model: all models combined, Opus, and Sonnet.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

B3.2/5.0

Behavior2/5

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

No annotations are provided, so the description carries full burden. It discloses that the tool retrieves usage limits (implying a read-only operation) but lacks behavioral details such as authentication requirements, rate limits, error conditions, or response format. For a tool with zero annotation coverage, this is insufficient transparency.

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

Conciseness5/5

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

The description is a single, efficient sentence that front-loads the core action ('Get your 7-day weekly usage limits') and adds necessary detail ('broken down by model'). There is zero waste, making it highly concise and well-structured for quick comprehension.

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

Completeness3/5

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

Given the tool's simplicity (0 parameters, no output schema, no annotations), the description is adequate but has gaps. It explains what the tool does but lacks context on when to use it versus siblings, behavioral traits, or output details. For a read-only tool with no complex schema, it meets minimum viability but could be more complete.

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?

The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately adds no parameter information, focusing instead on the tool's purpose. A baseline of 4 is applied as it avoids redundancy while being complete for a parameterless tool.

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

Purpose4/5

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

The description clearly states the action ('Get') and resource ('weekly usage limits'), specifying the breakdown by model (all models combined, Opus, Sonnet). It distinguishes from siblings like 'get_usage' by focusing specifically on 7-day weekly limits rather than general usage. However, it doesn't explicitly contrast with 'check_rate_status' or 'get_session_usage', keeping it from a perfect score.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives like 'check_rate_status', 'get_session_usage', or 'get_usage'. It implies usage for checking weekly limits but offers no explicit context, prerequisites, or exclusions, leaving the agent to infer based on tool names alone.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

4 tool updatesv1.0.0Mar 22, 2026
- First observedcheck_rate_status
- First observedget_session_usage
- First observedget_usage
- First observedget_weekly_limits

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4/5.0

Disambiguation5/5

Each tool has a clearly distinct purpose with no overlap: check_rate_status monitors rate limiting status, get_session_usage shows 5-hour session data, get_usage provides a comprehensive subscription dashboard, and get_weekly_limits focuses specifically on weekly model breakdowns. The descriptions make it easy to distinguish between session-based, weekly, and rate limit monitoring functions.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern with 'get_' or 'check_' prefixes: check_rate_status, get_session_usage, get_usage, and get_weekly_limits. The naming is perfectly uniform and predictable, making it easy for agents to understand what each tool does based on its name alone.

Tool Count5/5

Four tools is ideal for this monitoring-focused server - it covers all essential usage tracking aspects without being overwhelming. Each tool serves a distinct monitoring function (rate limits, session usage, overall usage, weekly limits), and there are no redundant or missing tools for the server's purpose.

Completeness5/5

The tool set provides complete coverage for Claude usage monitoring: it covers rate limiting status, session-level usage, subscription-level usage, and weekly model breakdowns. There are no obvious gaps - agents can monitor all relevant usage dimensions from different time perspectives (real-time, 5-hour sessions, weekly cycles) and get both detailed breakdowns and summary views.

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

WHOOP — MissingMCPOAuth
com.missingmcp
WHOOP recovery, strain, sleep and workouts in Claude via official WHOOP OAuth. Free, open source.
Health & Wellness Fitness Tracking
24
Anthropic Billing B
io.github.mcp-dir
Anthropic organization usage and cost reporting through an admin API key connected by the user.
Payments & Billing Finance AI & Machine Learning
91
claude-context-bridgeOAuth
io.github.PhoenixFeuer32
Share context and questions between Claude instances — VS Code, claude.ai web, and mobile.
Communication Knowledge & Memory Developer Tools
2
Fitness AI ConnectorOAuth
io.github.fmp-projects
Garmin data in Claude & ChatGPT via the Garmin Health API. OAuth sign-in, no password sharing.
Health & Wellness Fitness Tracking
22

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Orellius-Archive/claudeusage-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

orellius-claudetracker

What it shows

MCP tool output (get_usage)

Rate-limited state

Statusline output

Color grading

Tools

Requirements

Installation

Option 1: claude mcp add (recommended)

Option 2: Manual config

Optional: Statusline integration

How it works

Authentication

Token issues?

Rate limiting

Who is this for?

License

Available Tools

TDQS

TDQS

TDQS

TDQS

Tool Schema Changelog

TDQS

Resources

Related MCP Connectors

Latest Blog Posts

MCP directory API

MCP tool output (`get_usage`)

Option 1: `claude mcp add` (recommended)