UserProofHow to use Microsoft Clarity’s MCP server in Claude Code
Disclosure: UserProof publishes this guide and sells a different tool, named at the end. The setup steps come from Microsoft’s README and docs, read October 26, 2026. We did not hands-on test the Clarity MCP server for this page.
To use Microsoft Clarity from Claude Code, generate an API token in Clarity (Settings, Data Export, Generate new API token), then run claude mcp add clarity -- npx @microsoft/clarity-mcp-server --clarity_api_token=YOUR_TOKEN. The server gives your agent three tools: dashboard queries in plain English, a filtered list of session recordings, and Clarity’s documentation. The token it uses is a Data Export API token, and Microsoft’s docs for that API list 10 requests per project per day and data from the last 1 to 3 days.
Jump to: setup in 4 steps · the 3 tools · limits · prompts to try · when you need more · FAQ
Setup in 4 steps
- Have Clarity recording your site. Clarity is free with no traffic limits, per its FAQ. You need Node.js 16 or newer for the server.
- Create the token. In your Clarity project: Settings, Data Export, Generate new API token. Name it 4 to 32 characters, letters, numbers, hyphens, underscores or periods. Only project admins can manage tokens.
- Add the server to Claude Code.
The README also documents a VS Code install button, a Claude Desktop extension, and a generic JSON config for any MCP client.claude mcp add clarity -- npx @microsoft/clarity-mcp-server --clarity_api_token=YOUR_TOKEN - Check it. Run
claude mcp list, then ask “What are the most used browsers in my Clarity project?”, an example from the README.
The 3 tools
| Tool | What it does (README) | Example from the README |
|---|---|---|
query-analytics-dashboard | Retrieves analytics data and metrics from your project’s dashboard from a plain-language query | “How many Clarity sessions did we get from Egypt in the past 3 days?” |
list-session-recordings | Lists recordings filtered by URL, device, browser, OS, country, city and more | “Get Clarity recordings where users encountered JavaScript errors” |
query-documentation-resources | Pulls snippets from Clarity’s documentation | “How to track custom events using Microsoft Clarity?” |
Limits to plan around
| Limit | Value | Source |
|---|---|---|
| API requests | 10 per project per day | Data Export API docs |
| Data window | The previous 1 to 3 days (numOfDays 1, 2 or 3) | Data Export API docs |
| Breakdowns | Up to 3 dimensions per request: browser, device, country, OS, source, medium, campaign, channel, URL | Data Export API docs |
| Rows | 1,000 per response, no pagination | Data Export API docs |
| Recording retention in Clarity | 30 days from the time of recording; heatmaps up to 9 months | Clarity FAQ |
| Consent | Where local rules require it, Clarity needs explicit consent before cookies, or recordings are affected | Clarity FAQ |
The README does not say whether every tool call counts against the Data Export API quota. Treat the 10-a-day figure as the ceiling until you see otherwise, and keep each request to one question, as the README advises.
Prompts to try
- “Show traffic for my Clarity project for the last 3 days broken down by device and channel.”
- “Which URLs had the most rage clicks in the last 2 days?” (rage click count is a listed metric)
- “List recent mobile recordings on /pricing with JavaScript errors.”
- “How do I mask sensitive content in Clarity?” (documentation tool)
When you need more than the Clarity MCP
The server answers questions about the last 3 days and lists recordings for you to open. Your agent still decides what to change, and nothing checks whether a change worked. If you want the agent handed one fix with the file and line, ranked by your signup or checkout goal and re-checked after you ship it, that is what UserProof does: free for 3 sites and 5,000 recorded visits a month, $29 for 50,000. Comparison: UserProof vs Microsoft Clarity. Other servers: PostHog MCP vs UserProof, LogRocket, Sentry.
In 94 answers about session replay tools from ChatGPT, Claude and Gemini (our scan, October 20, 2026), Microsoft Clarity was named in 74, more than any tool except PostHog.
Set up UserProof from the home page
FAQ
Does Microsoft Clarity have an MCP server?
Yes. Microsoft publishes @microsoft/clarity-mcp-server on GitHub under the MIT license, with three tools: query-analytics-dashboard, list-session-recordings and query-documentation-resources.
How do I add the Clarity MCP server to Claude Code?
Generate a token in Clarity under Settings, Data Export, then run: claude mcp add clarity -- npx @microsoft/clarity-mcp-server --clarity_api_token=YOUR_TOKEN
What are the Clarity API limits?
The Data Export API docs list 10 requests per project per day, data from the previous 1 to 3 days, up to 3 dimensions per request and 1,000 rows per response with no pagination.
Can Claude watch Clarity recordings?
The list-session-recordings tool lists recordings that match filters such as URL, device and country. The README does not describe a tool that returns what happened inside a recording.
Is the Clarity MCP server free?
Clarity is free with no traffic limits per its FAQ, and the server is open source under MIT. You need Node.js 16 or newer.
Sources
- Microsoft Clarity: Clarity MCP server README; Clarity Data Export API docs; Clarity FAQ (read October 26, 2026)
- UserProof: UserProof pricing; UserProof setup; plugin and MCP source (read October 26, 2026)
- AI answer counts: UserProof scan of 94 discovery answers from ChatGPT, Claude and Gemini, October 20, 2026
Corrections
If a fact here is out of date, the vendor’s own page is the source of truth. Report it through our GitHub issues. We re-read these pages every quarter.