Claude Usage MCP Server

An MCP (Model Context Protocol) server that fetches your Claude usage data from the claude.ai dashboard, with automated daily tracking.

Features

• 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

Installation

# 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 chromium

Configuration

Add 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"]
    }
  }
}

Usage

First Time Setup

1. In Claude Code, run the claude_login tool
2. A browser window will open - complete Cloudflare verification and log in to Claude
3. After login, the session is saved automatically

Fetching Usage

There are multiple ways to fetch your usage:

1. Via MCP Tool (in Claude Code)

Simply ask Claude to check your usage, or use the get_claude_usage tool directly.

2. Via launchctl (manual trigger)

launchctl start com.claude.usage-fetcher

3. Via script directly

cd /path/to/claude-usage-mcp
.venv/bin/python fetch_usage.py

Automated Daily Tracking

A 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.

Setup Automation

# 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

Manage Automation

# 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.log

Tools

Tool	Description
get_claude_usage	Fetch usage data from the Claude dashboard
claude_login	Open browser window for authentication
check_claude_auth	Check if current session is authenticated

Data Format

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
  }
]

How It Works

1. Uses Playwright with a persistent Chrome profile
2. Bypasses Cloudflare by running in headed mode (positioned offscreen)
3. Stores browser data in browser-data/ directory
4. Scrapes the usage page and returns structured data

Security

• 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

Troubleshooting

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.