# Clarity MCP Server

A Model Context Protocol (MCP) server that bridges Microsoft Clarity's analytics API with Claude, adding custom date ranges and page-level filtering on top of Clarity's native limitations.

## Why This Exists

Microsoft Clarity's public API exposes only a rolling 1–3 day lookback window and lacks page-level filtering — requesting URL breakdowns across an entire site can return thousands of rows and crash on size limits. This server solves both problems:

1. **Custom date ranges**: Capture daily snapshots automatically (or manually trigger them), then query any historical range you've captured. Past data before captures began is unrecoverable (Clarity itself doesn't store it), but from the day you start using this, your full historical record accumulates.
2. **Page-level filtering**: Filter results by URL substring *after* Clarity returns data (post-processing), avoiding the oversized-response crashes and letting you focus on specific pages without re-querying.

## What You Get

Three tools accessible from Claude:

- **`get_clarity_insights`** — fetch live Clarity data (last 1–3 days) with optional URL filtering
- **`capture_clarity_snapshot`** — manually save today's data locally so it survives past Clarity's 3-day window
- **`get_clarity_historical_insights`** — query any date range you've captured, with optional URL filtering

## Hard Limits (Microsoft's, Not Ours)

| Constraint | Value |
|---|---|
| Requests per project per day | 10 |
| Date range | Rolling 1, 2, or 3 days (no arbitrary historical windows) |
| Dimensions per request | Max 3 |
| Response size | Max 1,000 rows, no pagination |

These are baked into Clarity's public API and aren't configurable. Plan your queries accordingly.

## Prerequisites

- Node.js v18+
- An active Microsoft Clarity project with **admin access** (only admins can generate API tokens)
- Claude Desktop (for MCP integration)

## Setup

### 1. Generate an API Token

1. Go to your Clarity project → **Settings** → **Data Export**
2. Click **Generate new API token** (requires project admin)
3. Name it (4–32 alphanumeric chars, plus `-`, `_`, `.`)
4. Copy immediately — shown once

### 2. Install This Server

```bash
git clone https://github.com/mad7droid/clarity-mcp-server.git
cd clarity-mcp-server
npm install
npm run build
```

### 3. Configure

Create `.env` in the project root:
```
CLARITY_API_TOKEN=your_jwt_token_here
```

### 4. Wire Into Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "clarity": {
      "command": "node",
      "args": ["/path/to/clarity-mcp-server/dist/index.js"],
      "env": {
        "CLARITY_API_TOKEN": "your_jwt_token"
      }
    }
  }
}
```

Replace `/path/to/clarity-mcp-server` with the actual path.

### 5. Restart Claude Desktop

Fully quit and reopen Claude Desktop. The Clarity tools should now appear.

## Usage

### Live Insights (Last 1–3 Days)

Ask Claude:
> "What's my site traffic for the last 2 days, broken down by device and OS?"

Claude will call `get_clarity_insights` with `numOfDays: 2, dimension1: "Device", dimension2: "OS"`.

### Page-Level Filtering

Ask Claude:
> "Show me traffic to /dashboard for the last day."

Claude will call `get_clarity_insights` with `urlFilter: "/dashboard"`. The URL dimension is auto-added if needed, and results are filtered post-fetch to avoid oversized responses.

### Capture Today's Data

Ask Claude:
> "Save today's analytics snapshot."

Claude will call `capture_clarity_snapshot`, writing `data/YYYY-MM-DD.json` locally. **This uses 1 of your 10 daily requests.**

### Query Historical Ranges

Ask Claude:
> "Show me traffic from July 15 to July 20."

Claude will call `get_clarity_historical_insights` with your requested dates. It returns:
- **Found dates**: snapshots available locally
- **Missing dates**: days you didn't capture (permanently unrecoverable — Clarity never stores them)
- **Data**: per-day snapshots with optional URL filtering applied

## Important Notes

### Daily Capture Strategy

To build a useful historical archive, run `capture_clarity_snapshot` roughly daily. A few tips:

- **One call per day is enough**: Each call captures the full URL breakdown. Calling multiple times same day just overwrites.
- **Historical depth**: After 3 days without a capture, that date is lost forever (Clarity's API won't return it).
- **Fire and forget**: Set a daily reminder in your calendar, or ask Claude each morning. No background daemon needed.

### URL Filtering Behavior

- Filtering happens *after* Clarity returns data (post-processing).
- Results are still bound by Clarity's 1,000-row upstream limit — if Clarity already dropped rows before your filter sees them, they're gone.
- Case-insensitive substring matching: `urlFilter: "/admin"` matches `/admin`, `/Admin/Users`, etc.

### Historical Query Limitations

`get_clarity_historical_insights` only returns data for days you've captured. There is no way to backfill older dates after the fact; only days you explicitly captured with `capture_clarity_snapshot` are available.

If you started using this server on July 20, you cannot later retrieve data from July 10–19, even if Clarity still has it in the live window — the data was never captured locally.

## Examples

### Example 1: Diagnose a High-Traffic Day

```
You: "Show me the top 20 pages from yesterday by traffic volume."
Claude: Calls get_clarity_insights { numOfDays: 1, dimension1: "URL" }
```

### Example 2: Track a Page's Performance Over Time

```
You: "What was the traffic to /checkout over the last 7 days?"
Claude: Calls get_clarity_historical_insights { startDate: "2026-07-14", endDate: "2026-07-20", urlFilter: "/checkout" }
         Returns data from whichever days you captured, lists missing dates.
```

### Example 3: Compare Devices Across a Week

```
You: "How does mobile traffic compare to desktop for the last 7 days?"
Claude: Calls get_clarity_historical_insights for the range, but notes that Device breakdown is not available historically (only live data via get_clarity_insights has Device dimension).
         Suggests querying the last 3 days live instead for an accurate comparison.
```

## Architecture

See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for a deep dive into the code structure and module responsibilities.

## Integration with Claude

See [`docs/CLAUDE_DESKTOP_SETUP.md`](docs/CLAUDE_DESKTOP_SETUP.md) for detailed Claude Desktop integration steps and troubleshooting.

## Error Handling

| HTTP Code | Meaning | Fix |
|---|---|---|
| 401 | Missing/invalid/expired token | Regenerate in Data Export settings |
| 403 | Token not authorized for this project | Verify token is from the correct project |
| 400 | Invalid parameters | `numOfDays` must be 1/2/3; dimensions must match the supported list |
| 429 | Daily limit (10/project) exceeded | Wait for daily reset (~24h) |

## Supported Dimensions

When requesting breakdowns, use one or more of:

`Browser`, `Device`, `Country/Region`, `OS`, `Source`, `Medium`, `Campaign`, `Channel`, `URL`

**Note:** Historical snapshots are captured with URL dimension only. Other dimensions are only available for live queries (last 1–3 days).

## License

MIT. See [`LICENSE`](LICENSE) for details.

## Contributing

Contributions are welcome. Please open an issue or pull request on GitHub.

## References

- [Clarity Data Export API Docs](https://learn.microsoft.com/en-us/clarity/setup-and-installation/clarity-data-export-api)
- [MCP Specification](https://modelcontextprotocol.io/)