Microsoft Clarity Link

Microsoft Clarity Link is an MCP server that connects AI assistants to Microsoft Clarity's behavioral analytics platform, providing access to user session recordings, heatmaps, and engagement metrics. This MCP bridge enables language models to query website analytics data, interpret user behavior patterns, and generate actionable UX insights without requiring direct access to the Clarity dashboard.

When to Use This MCP Server

Connect this server when...

• You want AI-driven analysis of user behavior data including session recordings, click heatmaps, and scroll patterns
• Your team uses Microsoft Clarity for web analytics and you need conversational access to engagement metrics
• You are conducting UX audits and want to identify rage clicks, dead clicks, and excessive scrolling patterns automatically
• You need to correlate user behavior data with specific pages or user segments for targeted improvements
• You want to generate automated reports summarizing user interaction patterns across your website

Consider alternatives when...

• Your analytics stack is built on Google Analytics, Mixpanel, or Amplitude without Clarity integration
• You need real-time analytics dashboards rather than conversational query access
• Your website does not have the Clarity tracking script installed

Quick Start

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

Connection setup:

1. Sign in to clarity.microsoft.com and navigate to your project
2. Generate an API token from Settings > API Access in your Clarity project
3. Add the configuration above to your .mcp.json file with your token
4. Restart your MCP client to connect to Clarity

Example tool usage:

# Analyze rage click patterns
> Show me the top 10 pages with the highest rage click rates this week

# Review session metrics
> What is the average session duration and scroll depth for mobile users?

# Identify UX problems
> Find pages where users have the highest dead click rates and suggest improvements

Core Concepts

Concept	Purpose	Details
Session Recordings	User journey capture	Full replays of individual user sessions showing mouse movements, clicks, scrolls, and page navigations
Heatmaps	Interaction visualization	Aggregated click, scroll, and attention maps that reveal where users engage most on each page
Rage Clicks	Frustration detection	Rapid repeated clicks in the same area indicating user frustration with unresponsive UI elements
Dead Clicks	Usability gaps	Clicks on non-interactive elements where users expected a response, revealing misleading affordances
Smart Events	Behavioral signals	Automatically detected patterns like quick-backs, excessive scrolling, and JavaScript errors

Architecture:

+------------------+       +------------------+       +------------------+
|  Microsoft       |       |  Clarity MCP     |       |  AI Assistant    |
|  Clarity         |<----->|  Server (npx)    |<----->|  (Claude, etc.)  |
|  Analytics API   | HTTPS |  stdio transport  | stdio |                  |
+------------------+       +------------------+       +------------------+
        |
        v
+--------------------------------------------------+
|  Sessions > Heatmaps > Events > Metrics > Funnels |
+--------------------------------------------------+

Configuration

Parameter	Type	Default	Description
clarity_api_token	string	(required)	API token generated from your Clarity project settings for authenticated access
project_id	string	(auto-detect)	Specific Clarity project ID when you have multiple projects configured
date_range	string	last_7_days	Default date range for queries (last_24h, last_7_days, last_30_days, custom)
include_recordings	boolean	true	Whether to include session recording metadata in query results
max_sessions	integer	100	Maximum number of session records returned per query to control response size

Best Practices

1. Filter by device type for targeted analysis. Mobile and desktop users exhibit fundamentally different interaction patterns. Always specify the device type when analyzing heatmaps or session metrics to avoid conflating touch-based mobile behavior with mouse-based desktop interactions. This separation produces more actionable insights.

2. Focus on smart events for rapid issue detection. Rather than manually reviewing session recordings, start with Clarity's smart events like rage clicks, dead clicks, and quick-backs. These automatically detected signals pinpoint the highest-impact UX issues and direct your attention to the pages and elements that need the most improvement.

3. Use time-bounded queries to track changes. When analyzing the impact of UX changes, compare metrics before and after deployment. Query specific date ranges around your release dates to measure whether rage click rates decreased, scroll depth improved, or session duration changed after your updates.

4. Combine Clarity data with conversion funnels. Clarity behavioral data is most powerful when correlated with conversion metrics. Ask the AI to compare behavior patterns between users who completed key actions (purchases, signups) and those who abandoned, revealing the specific UX friction points that drive drop-off.

5. Respect user privacy in analysis. Clarity automatically masks sensitive input fields, but be mindful of how you use session data. Avoid requesting individually identifiable session details and focus on aggregated patterns and anonymized behavioral metrics for your analysis.

Common Issues

"Invalid token" error when connecting. Verify that your API token was generated from the correct Clarity project. Tokens are project-scoped and will not work across different projects. Regenerate the token from Settings > API Access if it has expired or been revoked.

Heatmap data appears incomplete or empty. Heatmaps require sufficient traffic volume to generate meaningful visualizations. If a page has very few visits, the heatmap data will be sparse. Ensure the Clarity tracking script is correctly installed on the pages you are analyzing by checking the Clarity dashboard for data ingestion status.

Session recording queries return timeout errors. Queries that span large date ranges with many sessions can exceed API timeout limits. Narrow your date range, add page URL filters, or reduce the max_sessions parameter. For historical analysis covering months of data, break the query into weekly segments and aggregate the results.