Microsoft Clarity MCP Server: Ask Claude Why Visitors Rage Click

This information is correct as of September 2026. The Clarity MCP server is under active development, so details may change; Growth Method has made every attempt to ensure the accuracy and reliability of the information provided.

Is there a Microsoft Clarity MCP server that lets Claude read your session recordings and behaviour data? Yes. Microsoft ships an official, open-source Model Context Protocol server for Clarity as the npm package @microsoft/clarity-mcp-server. It runs locally next to your AI client, authenticates with a Clarity Data Export API token, and exposes three read-only tools: a natural-language query against your dashboard metrics, a filtered list of session recordings, and a search of Clarity’s own documentation. It is free, it works with Claude Desktop, Claude Code, Cursor, VS Code and any other MCP client, and it comes with a daily request limit that shapes how you should use it.

Clarity is the free behavioural analytics tool most marketing teams already have installed, often next to a paid Hotjar or Contentsquare seat they use less than they planned to. What the MCP server changes is what happens to that data: rage clicks, dead clicks, scroll depth and session recordings become inputs an assistant can reason over alongside your codebase, your GA4 property and your campaign plan. Watching recordings on a Friday afternoon is a different job.

What the Clarity MCP server is (and is not)

Microsoft Clarity records sessions, builds heatmaps and flags friction signals (rage clicks, dead clicks, quick backs, excessive scrolling, JavaScript errors) for free, with no traffic caps. We compare it with Hotjar in Hotjar vs Microsoft Clarity.

The MCP server is the bridge between that data and your AI assistant. Microsoft announced it on 4 June 2025 in a blog post by Clarity software engineer Ahmed Osman, who summarised the protocol in a line that has since become the standard explanation:

“MCP is like USB-C, but for AI.”

Ahmed Osman, Software Engineer, Microsoft Clarity (Clarity blog)

A few things it is worth being precise about, because the name invites assumptions:

• It is a local server, not a hosted connector. You run it with npx on your machine (or wherever your MCP client runs) and it calls Microsoft’s MCP endpoints on clarity.microsoft.com on your behalf. There is no OAuth sign-in and no remote URL to paste into Claude’s connector settings, which is the opposite of how the Sitebulb MCP and Notion MCP work.
• It authenticates with a project-scoped API token. The same Data Export API token that only a project admin can generate. One token, one Clarity project.
• It does not return heatmaps. It returns the numbers behind them (scroll depth, click counts, friction events) and lists of recordings with links. Predictive heatmaps are on Microsoft’s roadmap for the server, not in it.
• It does not cover AI Visibility. Clarity’s newer Bot Activity, Citations and Topic Insights reports are dashboard-only for now. More on where they fit below.
• It is open source under MIT. The GitHub repository has around 114 stars and its most recent change (February 2026) added a one-click VS Code install. Earlier releases wrapped the Data Export API in a single tool; version 2.0 (September 2025) introduced the three tools described next, each backed by a dedicated MCP endpoint.

If MCP itself is new to you, our introduction to MCP for marketers covers the basics, and MCP vs API explains why this is different from Clarity’s plain export API.

The three tools

The server registers three tools. Their names matter because you will see them in your client’s tool list and in the assistant’s reasoning.

The dashboard tool covers what the Clarity dashboard shows: users and sessions by device, browser, OS and country; popular pages, referrers, channels, campaigns and sources; smart events; scroll depth and click patterns; JavaScript errors; Core Web Vitals; and the friction metrics (quick backs, dead clicks, rage clicks). Microsoft’s own examples of a good query are “Page views count for the last 7 days” and “Distinct users visited https://www.example.com page last month”. Its examples of a bad one are “Analyze user behavior” and “Get all metrics”.

The session-recordings tool’s filter schema is the same segmentation the Clarity UI offers, which means you can ask for sessions by:

• Traffic: referring URL, UTM source, medium and campaign, and a channel classification that includes AITools and PaidAITools alongside organic search, paid search, social, email and direct.
• Behaviour: rage clicks, dead clicks, quick backs, excessive scrolling, JavaScript errors, click errors, clicked text, text entered, and Clarity’s “session intent” score (low, medium, high).
• Journey: entry, exit and visited URLs with contains, starts-with, regex and exclusion operators; page count; session and page duration; scroll depth.
• Audience and device: new versus returning, country, state and city, device type, browser and OS.
• Performance: performance score, Largest Contentful Paint, Cumulative Layout Shift and First Input Delay.
• Commerce: smart events (Purchase, AddToCart, SignUp, RequestQuote and around 40 others), product name, brand, price, rating, availability, purchases and checkout abandonment step.

So “list mobile sessions from AI tools last week that rage clicked and never reached /pricing/” is a single tool call, not a research project. The result is metadata (session links, duration, interaction timeline), not the video. You still open the recording in Clarity to watch it, but the assistant has done the triage.

The limits, honestly

Microsoft’s MCP documentation and the Data Export API reference both state the same quotas:

Two things complicate the picture. First, those figures are documented for the Data Export API, while the MCP server’s dashboard and recordings tools call separate endpoints under clarity.microsoft.com/mcp. Second, Microsoft’s own advanced queries post asks for “the last 30 days” and “the past month compared to the previous month”, and the server’s built-in guidance uses “last month” as a good example. We have not seen Microsoft reconcile the two in writing. The safe reading is that the 10-a-day budget is real, the 3-day window may or may not apply to the MCP endpoints, and you should test a 30-day question on your own project before building a workflow that assumes it works.

The budget also does not compound with the number of people. Ten requests per project per day means a team of five sharing one token gets two questions each, and a compound question the assistant breaks into three tool calls costs three. There is no self-service way to raise it: when a user asked on Microsoft Q&A in January 2026, Microsoft Advertising support confirmed there is no dashboard setting and no paid tier, and pointed to clarityms@microsoft.com for quota requests and the dashboard’s custom download (up to 100,000 sessions) as the bulk alternative. “Increased API limits” is the first item on Microsoft’s published roadmap for the server.

Amir Sibaee, a Google Ads and media-buying specialist who wrote up the setup for CRO work, put the practical consequence well:

“For now, treat the 10 daily requests as a constraint that requires prioritising your most valuable queries rather than using the integration for casual browsing.”

Amir Sibaee, Google Ads and media buying specialist (as86.pro)

In practice that means: decide the question before you open the chat, ask for one metric at a time (which is what the server’s own instructions tell the assistant to do anyway), and keep the documentation tool for questions about Clarity rather than about your site, since it does not touch your data.

Setting it up

Setup has two halves: get a token, then tell your client how to run the server.

1. Generate a Data Export API token

In your Clarity project go to Settings, then Data Export, then Generate new API token. Give it a name (4 to 32 characters, letters, numbers, hyphens, underscores and full stops) and copy it once; it is not shown again. Only project admins can do this. The token is a bearer secret scoped to that one project, so treat it like a password: never commit it, never put it in client-side code, and replace it when someone with access leaves the project (Microsoft’s own best-practice list says the same).

2. Connect your client

Claude Desktop. The quickest route is the extension gallery: open File, then Settings, then Extensions, search for “Microsoft Clarity”, click Install and paste the token when prompted. If you prefer the config file, add this to claude_desktop_config.json (~/Library/Application Support/Claude/ on macOS, %AppData%\Claude\ on Windows) and restart Claude:

{
  "mcpServers": {
    "@microsoft/clarity-mcp-server": {
      "command": "npx",
      "args": [
        "@microsoft/clarity-mcp-server",
        "--clarity_api_token=your-api-token-here"
      ]
    }
  }
}

Claude Code. One command, at user scope so it is available in every project on the machine:

claude mcp add --scope user clarity -- npx -y @microsoft/clarity-mcp-server --clarity_api_token=your-api-token-here

Restart Claude Code and ask “What are the top dead clicks on my site in the last 3 days?” to confirm the tools are live.

VS Code. The repository README has an “Install Server” button that registers the server in VS Code’s MCP settings; you add the token afterwards.

Cursor and everything else. The JSON block above is the generic MCP client configuration; paste it wherever your client keeps MCP server definitions.

Growth Method. Clarity is one of the MCP servers our MCP client is built to talk to, so a campaign in the Analysing stage can pull friction data into its results without anyone leaving the app. See connecting an integration for the general steps.

The prerequisites are Node.js 16 or later and a Clarity project that has been collecting data for at least a few hours; a brand-new project will return empty results for the first afternoon.

Prompts worth stealing

Microsoft’s guidance comes from two places that pull in slightly different directions. The server’s built-in instructions tell the assistant to keep every dashboard query “SIMPLE, SINGLE-PURPOSE” with an explicit time range, and to break compound requests into separate calls. The advanced queries post from August 2026 then gives five compound prompts, each with a mock output and the reasoning behind it:

1. “Show me pages with average scroll depth above 75% but conversion rate below 5% for the last 30 days.” Engaged readers who do not convert usually means the call to action is weak or invisible.
2. “List sessions where users exhibited rage clicks AND excessive scrolling AND quick backs in the last 7 days.” Stacked friction signals find the pages single metrics miss.
3. “Show average engagement time for mobile users from organic search in North America vs Europe, broken down by browser.” Segment before you diagnose.
4. “List pages where average session duration changed by more than 20% over the past month compared to the previous month.” Trend, not snapshot.
5. “Fetch session recordings for pages with low scroll depth and high exit rate last week.” Numbers tell you where; recordings tell you why.

There is no contradiction here once you know how the pieces fit. You ask the compound question; the assistant decomposes it into single-purpose tool calls, which is exactly what the server instructions are for. Just remember each of those calls draws on the daily budget.

Microsoft’s tips for writing your own are worth keeping to hand: combine multiple metrics, segment across dimensions, incorporate time-series comparisons, filter sessions by behavioural triggers, use clear and specific language, document and reuse queries, and visualise outputs.

Three more from us, aimed at marketing teams rather than analysts:

• Campaign post-mortem: “For sessions with UTM campaign ‘spring-launch’ in the last 3 days, compare scroll depth, dead clicks and smart-event completions against all other paid search sessions.”
• AI traffic check: “List sessions from the AITools channel last week, sorted by click count, and tell me which pages they landed on and whether any rage clicked.” (The channel filter exists in the server’s schema; whether your project has enough AI-referred sessions to make it useful is another matter.)
• Release check: “Compare JavaScript errors and rage clicks on /pricing/ for the last 3 days against the 3 days before the release” is two calls, and a good habit after every site change.

The best use we have seen is the one where the assistant also has the codebase open. Ryan Frizelle, who publishes Claude Code walkthroughs, runs a weekly loop of “pull the top dead clicks and rage clicks from the last 7 days, hypothesise a cause for each, propose the fix in my codebase, but change nothing until I say so”:

“Claude Code now has eyes on your Clarity data AND access to your codebase. It finds an issue, explains what’s happening, then fixes it.”

Ryan Frizelle, ryanfrizelle.com (Microsoft Clarity + Claude Code Setup)

That “change nothing until I say so” clause is the important part of his prompt, and it is a good default for any read-only analytics MCP paired with a coding agent.

Where AI Visibility fits

Clarity’s biggest change in 2026 sits outside the MCP, and it explains both what the presentation was selling and what the server cannot yet reach.

Microsoft has been building an AI Visibility suite inside Clarity, on the argument that a growing share of buying decisions now happens inside an AI answer before anyone reaches your site, where traditional web analytics is blind. Ihab Rizk of Microsoft Clarity framed it this way when launching the first of those reports in January 2026:

“For years, analytics have told only half the story. You could see what people did on your site: where they clicked, how far they scrolled, what they converted on. But a growing share of traffic was happening quietly in the background, invisible to traditional tools.”

Ihab Rizk, Microsoft Clarity (Clarity blog)

The suite now has three reports, all free:

• Bot Activity (January 2026): which AI crawlers and agents request your site, how often, and which paths they hit, from server-side logs via a connected CDN (Cloudflare and others; the WordPress plugin enables it by default). Microsoft is careful to say a request “doesn’t indicate that content was retrieved, grounded, cited, or surfaced”. Our AEO guide covers how to use it.
• Citations (generally available 13 May 2026): the grounding queries AI assistants ran, which of your pages they cited, and your share of authority against other cited domains. Requires domain verification through Bing Webmaster Tools or Google Search Console. Since August it splits branded from non-branded queries.
• Topic Insights (beta, 9 July 2026): you define the topics, prompts and competitors, and Clarity reports visibility, influence and gaps with recommended actions.

A mid-2026 Microsoft Advertising presentation by Megan Pakes, Director of Product Marketing, made the case for treating this as one workflow: see where AI finds and cites you, then see what AI-referred visitors do after they arrive, because “a search a competitor won is a page you owe” and an AI-referred visitor “usually needs confirming: price, stock, shipping, proof” rather than convincing. The same deck previewed a conversational analyst inside Clarity, currently a pilot by application, that reads hundreds of thousands of sessions to answer questions like “are visitors from other European countries hesitating because of shipping costs?” and shows its working. If that ships, it is the in-product counterpart to what the MCP lets you do in your own assistant today.

Microsoft’s supporting benchmark is its own: a November 2025 study of 1,277 publisher and news sites over eight months found AI referrals grew 155.6% against 24% for search, still made up under 1% of traffic, and converted to sign-ups at 1.66% versus 0.15% from search. Publisher sites, sign-up clicks as the conversion, and a vendor with a product to sell, so treat it as directional. The pattern matches what we hear from B2B teams: small, growing, and worth segmenting before you judge it.

What this means for the MCP. The server exposes none of the AI Visibility data today. What you can do is the after-the-click half: the recordings tool’s AITools and PaidAITools channel filters let you pull AI-referred sessions and ask whether they behave the way the presentation says they should (shorter, more focused, straight to price and proof). Pair that with a Search Console connector for the before-the-click half and the assistant can reason across both. When Microsoft adds AI Visibility to the MCP, and the roadmap’s “additional analytics features” line suggests it will, we will update this article.

Clarity MCP vs GA4 MCP vs PostHog MCP

Most teams will run the Clarity server next to at least one other analytics MCP. They answer different questions.

The honest summary: Clarity MCP is the cheapest and most constrained of the three. Use it for the “why did that page underperform” step after GA4 or PostHog has told you which page, and budget your ten questions for that.

Security: what a reviewer will want to know

• Read-only. All three tools read. There is no tool that changes a Clarity setting, deletes a recording or writes an event.
• Project-scoped bearer token. The token grants read access to one project’s dashboard data and recording metadata. It does not expose other projects on the account or account settings.
• Admin-only issuance and revocation. Only project admins can generate or replace tokens, from Settings then Data Export. Replacing a token invalidates the old one immediately.
• Local process, hosted endpoints. The server runs on your machine and sends the token as an Authorization: Bearer header to Microsoft’s endpoints. Nothing syncs in the background; data moves only when a tool is called.
• The token lives in a config file. Unlike OAuth connectors there is no sign-in flow, so the secret sits in claude_desktop_config.json or your client’s equivalent. Keep that file out of version control and out of shared machines.
• What happens after the data lands in the chat is governed by your agreement with Anthropic, OpenAI, Cursor or whoever runs the client, including training settings. Session recordings can contain personal data; if your privacy policy covers Clarity, check it covers where its output now travels.
• No pagination, 1,000 rows. A prompt cannot exfiltrate an entire project in one call, and ten calls a day caps the total.

Getting started checklist

1. Confirm Clarity is installed and has a few hours of data, and that you are a project admin (or know who is).
2. Generate a Data Export API token and store it somewhere safe.
3. Install the server in your client: extension gallery for Claude Desktop, claude mcp add for Claude Code, the JSON block for anything else.
4. Warm up with three single-purpose questions: top pages last 3 days, top dead clicks last 3 days, ten most recent mobile sessions with rage clicks.
5. Try one of Microsoft’s five advanced queries on a 30-day window and note whether it works on your project.
6. Write down the ten questions you actually want answered each day, and ration accordingly.
7. Connect GA4 or Search Console to the same assistant and ask the cross-tool question: “which of last week’s top landing pages had the most friction?”

Further reading

Microsoft’s own material, in the order you will need it:

• Microsoft Clarity MCP Server (Microsoft Learn)
• Clarity Data Export API, including token generation and limits
• microsoft/clarity-mcp-server on GitHub, and the npm package
• Introducing the Microsoft Clarity MCP Server (June 2025 launch post)
• 5 Advanced Queries You Should Try with the Clarity MCP Server (August 2026)
• Bot Activity overview, Citations and Topic Insights

Related reading from us:

• Hotjar vs Microsoft Clarity: which should you choose?
• GA4 MCP server: connect Google Analytics to Claude and Cursor
• Building a PostHog MCP server
• Answer engine optimisation: the practical guide
• The MCP servers directory for marketers
• MCPs, CLIs and Skills: which fits your workflow?
• An introduction to MCP for marketers

Where this is heading

Two predictions. First, the 10-a-day limit will go, because it is the only thing stopping the Clarity MCP from being the default way a marketing team reads behavioural data, and Microsoft has put “increased API limits” at the top of its own list. Second, AI Visibility will arrive in the server, and when it does the interesting prompts will straddle both halves: which grounding queries cite us, and what those visitors do once they land. Microsoft has already built the second half of that pipeline into the recordings filter. Until then, the MCP is a well-made, tightly rationed window onto one project, and the conversational analyst previewed in the deck is the clearer signal of where Microsoft thinks this ends up: the analyst inside the tool, reading every session, rather than your assistant pulling 250 at a time.

The bottom line

The Clarity MCP server is free, official, read-only and takes ten minutes to set up. It puts friction signals and session-recording triage inside the assistant you already use, and it pairs best with a coding agent that can also fix what it finds. Plan around 10 questions a day, keep each one single-purpose, test whether a 30-day window works on your project, and do not expect heatmaps or AI Visibility data through it yet.

About Growth Method

A rage-click finding is only useful once someone decides what to do about it, and that decision is what most teams lose between the dashboard and the sprint.

Growth Method is the agentic marketing platform for B2B teams. Pre-built AI agents plan, launch and analyse marketing campaigns from your live marketing data, with your martech stack connected in minutes. Clarity is one source among many: a friction finding becomes a campaign, gets prioritised against your goal, and is measured on the business outcome rather than the click count.

We are on-track to deliver a 43% increase in inbound leads this year. There is no doubt the adoption of Growth Method is the primary driver behind these results.

Laura Perrott, Colt Technology Services

If you would rather run more campaigns than ration API calls, get started here.

Frequently asked questions

What is the Microsoft Clarity MCP server?

It is Microsoft’s official, open-source Model Context Protocol server for Clarity, published as the npm package @microsoft/clarity-mcp-server under an MIT licence. It runs locally alongside an MCP client such as Claude Desktop, Claude Code, Cursor or VS Code, authenticates with a Clarity Data Export API token, and exposes three tools: a natural-language query against your dashboard metrics, a filtered list of session recordings, and a search of Clarity’s documentation.

Is the Clarity MCP server free?

Yes. Clarity itself is free with no traffic limits, and the MCP server is free and open source. The only costs are whatever you already pay for the AI client you connect it to. There is no paid tier to raise the API limits.

What are the Clarity MCP server’s limits?

Microsoft’s documentation states each project allows 10 API requests per day, a maximum of 3 days of data and up to 3 dimensions per request, with responses capped at 1,000 rows. Those figures come from the Data Export API. Microsoft’s own example prompts for the MCP ask for 30-day windows, so test on your project, but plan around 10 questions a day. Higher limits are on the roadmap rather than available today.

Can the Clarity MCP server show heatmaps or AI Visibility data?

No. Despite Clarity being best known for heatmaps, the MCP server returns dashboard metrics and session-recording lists, not heatmap images. It also does not expose the AI Visibility reports (Bot Activity, Citations, Topic Insights). Those still live in the Clarity dashboard. Predictive heatmaps are on Microsoft’s published roadmap for the server.

How do I connect Microsoft Clarity to Claude?

Generate a Data Export API token in your Clarity project (Settings, then Data Export; only project admins can do this). In Claude Desktop, install the Microsoft Clarity extension from the Extensions gallery and paste the token. In Claude Code, run claude mcp add with npx @microsoft/clarity-mcp-server and the token. Any other MCP client takes the same npx command in its JSON config.

Is the Clarity MCP server read-only?

Yes. All three tools read data: dashboard metrics, session-recording metadata and documentation snippets. Nothing writes back to Clarity, and the token cannot change project settings. The token is scoped to one project, so a multi-site team needs one token per project.