Microsoft Clarity MCP Server

Microsoft Clarity

Microsoft Clarity records how visitors use a website: sessions, scroll depth, engagement time, rage clicks, dead clicks, quick backs, script errors, and traffic sources. One Data Export token (Clarity → Settings → Data Export) powers all tools in this bundle.

Four API surfaces (same token)

Snapshot caching (all fetch tools)

Every upstream tool accepts refresh and allow_stale:

• Default: serve a fresh cached snapshot when one exists for the same upstream arguments (dimensions, date range, NL query, etc.).
• metric_names and compact on clarity_live_insights are local filters — they narrow a cached export without spending quota.
• When export quota is exhausted, set allow_stale=true (default) to read the latest cached export; only use refresh=true when the user explicitly wants a new upstream call.
• clarity_list_snapshots lists stored snapshots and quota windows for the connected credential.

Operational order

1. clarity_list_snapshots or a cached read when you only need data already fetched for this credential.
2. clarity_query_docs when the user needs setup, SDK, privacy, or feature guidance — no export quota cost.
3. clarity_live_insights with num_of_days=1 and no dimensions for a structured traffic pulse — only 10 calls/project/UTC day on this endpoint.
4. clarity_query_dashboard for exploratory NL questions when structured export is awkward — separate from the export quota.
5. clarity_list_recordings to find sessions with rage clicks, errors, or device filters — empty [] is normal on low-traffic projects.

For structured breakdowns, prefer one clarity_live_insights call with dimension_1 set rather than multiple aggregates. Use metric_names to trim a response locally without another export call.

Metrics from clarity_live_insights

Quotas and limits

• clarity_live_insights only: 10 requests per project per UTC day (HTTP 429 Exceeded daily limit). History window is 1–3 days; max 1,000 rows; no pagination; timestamps are UTC.
• clarity_query_dashboard, clarity_list_recordings, clarity_query_docs: use Microsoft's clarity.microsoft.com/mcp HTTP APIs with the same token. They are not blocked when the export daily cap is hit — plan agents around that split.
• Session recordings return metadata and links, not video files. Heatmap images are not exposed via API.
• Clarity is free; there is no paid tier to raise export limits today (Microsoft has noted higher limits on their roadmap).

Gotchas

• Low-traffic projects return HTTP 200 with zero/null metrics or empty recording arrays — use compact=true (default) on exports to drop empty sections.
• Each token is scoped to one Clarity project; agencies need one credential per project.
• clarity_query_dashboard works best with single-purpose questions and explicit time ranges; avoid multi-metric kitchen-sink prompts.
• Invalid dimension or metric names are rejected before the upstream export call.