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

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:

{
  "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 for a deep dive into the code structure and module responsibilities.

Integration with Claude

See 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 for details.

Contributing

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

References

• Clarity Data Export API Docs
• MCP Specification