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 Server how much of my usage limit have I used?"
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 (Model Context Protocol) server that fetches your Claude usage data from the claude.ai dashboard, with automated daily tracking.
Authenticate with Claude via browser login
Fetch session and weekly usage limits from the settings page
Persistent session with Cloudflare bypass
Automated daily usage tracking via launchd
Deduplication - one record per day, always up to date
Integrates directly with Claude Code
Related MCP server: Claude Session MCP
# Clone the repo
git clone https://github.com/mvacaporale/claude-usage-mcp.git
cd claude-usage-mcp
# Install dependencies
uv sync
# Install Playwright browsers
uv run playwright install chromiumAdd to your Claude Code MCP settings (~/.claude/settings.json):
{
"mcpServers": {
"claude-usage": {
"command": "uv",
"args": ["run", "--directory", "/path/to/claude-usage-mcp", "python", "server.py"]
}
}
}In Claude Code, run the claude_login tool
A browser window will open - complete Cloudflare verification and log in to Claude
After login, the session is saved automatically
There are multiple ways to fetch your usage:
Simply ask Claude to check your usage, or use the get_claude_usage tool directly.
launchctl start com.claude.usage-fetchercd /path/to/claude-usage-mcp
.venv/bin/python fetch_usage.pyA launchd job automatically fetches usage:
Daily at 11:00 PM
On login/wake (catches up if Mac was asleep)
Multiple runs in a day update the same record - you'll always have exactly one entry per day.
# Copy the plist to LaunchAgents (if not already there)
cp com.claude.usage-fetcher.plist ~/Library/LaunchAgents/
# Load the job
launchctl load ~/Library/LaunchAgents/com.claude.usage-fetcher.plist# Check if job is loaded
launchctl list | grep claude
# Trigger manually
launchctl start com.claude.usage-fetcher
# Disable
launchctl unload ~/Library/LaunchAgents/com.claude.usage-fetcher.plist
# Re-enable
launchctl load ~/Library/LaunchAgents/com.claude.usage-fetcher.plist
# View logs
tail -f usage-fetcher.logTool | Description |
| Fetch usage data from the Claude dashboard |
| Open browser window for authentication |
| Check if current session is authenticated |
Usage history is stored in usage-history.json:
[
{
"success": true,
"timestamp": "2026-01-25T23:00:00.000000",
"session_percent": 19,
"session_resets_in": "2 hr 15 min",
"weekly_all_models_percent": 10,
"weekly_resets": "Thu 10:00 AM",
"weekly_sonnet_percent": 0
}
]Uses Playwright with a persistent Chrome profile
Bypasses Cloudflare by running in headed mode (positioned offscreen)
Stores browser data in browser-data/ directory
Scrapes the usage page and returns structured data
Browser data stored locally (never committed to git)
No credentials stored - uses browser session cookies
Login happens in your own browser window
All sensitive files are gitignored
Cloudflare blocking: Run claude_login to re-authenticate manually.
Browser data locked: If you see lock errors, restart Claude Code (/mcp to reconnect).
Stale session: Delete browser-data/ and browser-data-scheduled/ directories, then run claude_login again.
Check if the current session is authenticated with Claude.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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 fails to specify what constitutes a successful check (boolean return? user object? exception?), whether the check modifies session state, or what latency/network requirements exist.
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?
Single sentence of ten words with zero redundancy. The core purpose is front-loaded and immediately comprehensible. Every word earns its place.
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?
Adequate for a zero-parameter tool but lacks critical information about return values since no output schema exists. For a status-checking tool, the description should ideally indicate what 'authenticated' means in terms of response data or side effects.
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?
Zero parameters with 100% schema coverage means the description carries baseline expectations. No parameter explanation is required, though the description implicitly confirms no inputs are needed to perform this check.
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?
States a specific action ('Check') and clear scope ('current session is authenticated with Claude'). However, it does not explicitly differentiate from sibling tool 'claude_login' (which establishes auth) despite the distinct purposes being inferable from names alone.
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?
Provides no guidance on when to invoke this tool versus alternatives. Does not indicate whether it should be called before other Claude operations, what to do if authentication fails, or how it relates to the 'claude_login' workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Open a browser window to authenticate with Claude. Use this if get_claude_usage fails due to authentication.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It adds critical behavioral context that this opens a browser window (interactive UI) rather than returning a URL or token silently. However, it omits completion behavior (blocking vs async), success indicators, or failure handling.
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?
Two well-structured sentences: first states purpose, second states usage condition. Front-loaded with action, zero redundancy, appropriate length for tool complexity.
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 simple 0-parameter auth utility without annotations or output schema, the description covers essential purpose and usage triggers. Could be improved by mentioning success/failure signals or timeout behavior, but adequately complete for selection purposes.
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?
Input schema has zero parameters. Per scoring rules, 0 params = baseline 4. The description appropriately contains no parameter discussion 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?
Clear specific verb ('Open') and resource ('browser window to authenticate with Claude'). The description effectively distinguishes this from sibling get_claude_usage by positioning it as the auth recovery mechanism.
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?
Excellent explicit guidance: 'Use this if get_claude_usage fails due to authentication.' States the exact trigger condition and identifies the sibling alternative, creating a clear decision tree for the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch Claude usage data from the dashboard. Returns daily token usage information.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It successfully discloses that the tool returns 'daily token usage information,' which is crucial given the lack of output schema. However, it fails to mention authentication requirements, rate limiting, supported date ranges, or whether the data is cached versus live.
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?
Two efficient sentences: first establishes the action and target, second describes the return value. No redundancy or filler content. Information is front-loaded with the verb 'Fetch.'
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?
While the description explains return values (necessary without output schema), it omits critical context given the sibling tools: authentication prerequisites and token/date range limitations. For a dashboard-accessing tool with auth siblings, mentioning the required auth state would make this complete.
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?
Zero parameters present, establishing a baseline of 4 per scoring rules. The description does not need to compensate for missing parameter documentation since the input schema requires none.
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?
Uses specific verb 'Fetch' with clear resource 'Claude usage data' and source 'dashboard.' The mention of 'daily token usage' precisely scopes the returned data. Clearly distinguishes from auth-related siblings (check_claude_auth, claude_login) by focusing on data retrieval rather than authentication.
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?
Provides no explicit guidance on when to use versus alternatives, prerequisites, or sequencing. Given the authentication-related siblings, the description should state that authentication is required first or recommend using check_claude_auth beforehand, but it remains silent on workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool has a clearly distinct purpose with no overlap: authentication checking, authentication initiation, and usage data retrieval. The descriptions make it easy to differentiate when to use each tool, avoiding misselection.
All tools follow a consistent snake_case pattern with clear verb_noun structure (check_claude_auth, claude_login, get_claude_usage). The naming is predictable and readable throughout the set.
Three tools is borderline thin for a usage monitoring server, as it covers only authentication and data fetching. While functional, additional tools for configuration, historical data, or notifications would make the scope more complete.
The tools cover the core workflow of authentication and usage retrieval well, with no dead ends. A minor gap exists in lacking tools for managing authentication sessions (e.g., logout) or advanced usage analytics, but agents can work around this.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
WHOOP recovery, strain, sleep and workouts in Claude via official WHOOP OAuth. Free, open source.
Persistent context for Claude. Your AI always knows your projects and next actions across sessions.
Persistent memory for Claude Code and Cursor. Stop re-explaining your project every session.
Persistent cross-session memory shared by Codex, Claude Code, ChatGPT, and other AI agents.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/mvacaporale/claude-usage-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server