# 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

```bash
# 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`):

```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)
```bash
launchctl start com.claude.usage-fetcher
```

#### 3. Via script directly
```bash
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

```bash
# 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

```bash
# 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`:

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