Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@.Microsoft Clarity MCP Server show me rage clicks and dead clicks from the last 3 days"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
microsoft-clarity-mcp)FastMCP server exposing Microsoft Clarity's Data Export API for behavioral UX analysis, rage clicks, dead clicks, quick backs, excessive scrolling, and JavaScript runtime errors.
Companion behavioral diagnostics engine to Google Analytics and Search Console for AI agents.
Run directly without installing via uvx (Python) or npx (Node):
uvx)uvx microsoft-clarity-mcpnpx)npx microsoft-clarity-mcpRelated MCP server: KrystalView MCP Server
Add to your MCP client config (claude_desktop_config.json, cursor.json, or Antigravity/OpenCode):
{
"mcpServers": {
"microsoft-clarity": {
"command": "uvx",
"args": ["microsoft-clarity-mcp"],
"env": {
"CLARITY_API_TOKEN": "your_clarity_api_token_here"
}
}
}
}Or using npx:
{
"mcpServers": {
"microsoft-clarity": {
"command": "npx",
"args": ["-y", "microsoft-clarity-mcp"],
"env": {
"CLARITY_API_TOKEN": "your_clarity_api_token_here"
}
}
}
}Microsoft Clarity secures data export via static JWT Bearer tokens:
Log in to Microsoft Clarity.
Open your project dashboard.
Navigate to Settings -> Data Export.
Click Generate new API token (provide a name between 4 and 32 alphanumeric characters, e.g. clarity-agent).
Copy the generated token and configure CLARITY_API_TOKEN.
Daily Quota: Microsoft Clarity strictly allows 10 requests per project per day.
Automatic Cache: To safeguard user quota from runaway agent loops, all responses are cached locally on disk at ~/.clarity_mcp/cache.json with a 1-hour TTL (configurable via CLARITY_CACHE_TTL).
Stale Cache Fallback: If the daily 10-request quota is reached, the server automatically serves stale cached data with an explicit warning, ensuring your agents remain operational without hard crashing.
Quota Transparency: Every tool response includes metadata detailing calls_used_today, remaining_today, and daily_limit.
Tool | Parameters | Description |
|
| High-level behavioral friction metrics: session counts, rage clicks, dead clicks, quick backs, excessive scroll, and JS errors. |
|
| Ranks friction severity broken down across URL paths, devices, browsers, operating systems, or countries. |
|
| JavaScript runtime exceptions and error clicks grouped across browsers and operating systems. |
|
| Diagnostic utility checking token format, cache integrity, and remaining daily API quotas. |
| (none) | Lists dynamic skill playbooks bundled with the server. |
|
| Fetches operational playbooks (e.g. |
| (none) | Queries PyPI for newer versions and upgrade commands. |
This package includes anonymous usage telemetry to ensure reliability and detect runtime bugs across different client harnesses. Telemetry adheres strictly to Schema v2:
Opt-Out: Strictly respects DO_NOT_TRACK=1, DISABLE_TELEMETRY=1, or CLARITY_TELEMETRY=false.
Zero PII: No user URLs, personal identifiers, or authentication tokens are ever captured.
MIT License. Copyright (c) 2026 Surendran B.
Check PyPI for newer versions of microsoft-clarity-mcp and get upgrade instructions.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose the key behavioral facts: it queries PyPI and returns upgrade instructions (implying a read-only, non-installing check). However, it omits network-dependency, failure modes (e.g., offline), and explicit confirmation that nothing is installed or modified.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence covering what it checks, against what source, and what the caller gets back. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be described, and there are no parameters to document. The description is complete for a simple 0-arg check, with only the sibling-relationship to 'doctor' left unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a 0-param tool is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (check) and resource (PyPI for newer versions of microsoft-clarity-mcp), plus the secondary outcome (upgrade instructions). It is clear what the tool does, but it doesn't distinguish itself from the sibling 'doctor' tool, which may also cover environment/diagnostic concerns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: call it when you want to know whether a newer release exists. There is no explicit when-to-use/when-not guidance and no mention of how it relates to alternatives like 'doctor', leaving the agent to infer the boundary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate Microsoft Clarity credentials, project configurations, on-disk cache, and remaining daily request quota.
| Name | Required | Description | Default |
|---|---|---|---|
| token | No | ||
| project_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It does disclose the scope of the check (credentials, config, cache, quota), which is useful and beyond raw schema. However, it omits whether the call is read-only, whether it consumes quota itself, whether it mutates the on-disk cache, and what failures look like.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with the verb first and an enumerated scope. Every element earns its place; there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-value explanation is not required. The core purpose is conveyed, but for a diagnostic tool with two undocumented optional parameters and no annotations, the definition leaves the agent guessing about override behavior and side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters (token, project_id) have 0% schema description coverage, so the description must compensate — and it does not mention either parameter at all. It gives no hint that these optional args override stored credentials or scope the validation to a project.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ("Validate") and enumerates exactly what is validated: credentials, project configurations, on-disk cache, and daily quota. This clearly reads as a diagnostic/health-check tool. It does not reference or differentiate itself from any sibling tool, but the purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance and no mention of alternatives. The agent must infer that this is for troubleshooting before or after calling the data tools in the sibling list. No prerequisites or exclusion conditions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Break down user frustration metrics (rage clicks, dead clicks, quick backs) across a specific dimension.
Args: project_id: Microsoft Clarity Project ID. dimension: Breakdown dimension: 'URL', 'Device', 'Browser', 'OS', or 'Country/Region'. Defaults to 'URL'. num_of_days: Lookback window in days (1, 2, or 3; defaults to 3). token: Optional Clarity API token.
Returns: Structured JSON ranking dimension values by user frustration severity.
| Name | Required | Description | Default |
|---|---|---|---|
| token | No | ||
| dimension | No | URL | |
| project_id | Yes | ||
| num_of_days | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the metric types covered, the 1/2/3-day window constraint, and that the result is a ranked JSON structure, which is real behavioral context. It omits auth/permission requirements (the token is only called 'optional'), rate limits, and any statement about data freshness or cost.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded purpose sentence followed by clearly separated Args and Returns blocks; the metric examples and value constraints each earn their space. It is slightly padded by restating parameter names that already appear in the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a four-parameter read-only analytics tool with an output schema already covering the return shape, the description supplies the missing parameter semantics, defaults, and value constraints. What remains absent is operational context (auth, rate limits, when to prefer this over sibling insight tools), which is a modest gap rather than a blocker.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and there are no enums in the schema, so the description must compensate — and it largely does, spelling out project_id, the five allowed dimension values with a default of 'URL', the restricted num_of_days values, and token optionality. The token entry is thin (no guidance on when it is needed or where it comes from), keeping this short of a 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb ('break down') and resource ('user frustration metrics') and even enumerates the underlying metrics (rage clicks, dead clicks, quick backs), so the agent knows exactly what this produces. It never names or contrasts with the plausible sibling get_ux_insights, so sibling differentiation is left to inference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the 'across a specific dimension' framing and the documented defaults, which tell the agent this is a read-only analytical breakdown. There is no explicit when-to-use, when-not-to-use, or routing guidance relative to get_ux_insights or get_js_errors.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyze JavaScript errors and unhandled exceptions across browsers and operating systems.
Args: project_id: Microsoft Clarity Project ID. num_of_days: Lookback window in days (1, 2, or 3; defaults to 3). token: Optional Clarity API token.
Returns: Structured JSON breakdown of JavaScript script errors and error clicks by Browser and OS.
| Name | Required | Description | Default |
|---|---|---|---|
| token | No | ||
| project_id | Yes | ||
| num_of_days | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses that the tool returns a structured JSON breakdown by Browser and OS, but omits key behavioral traits: whether it's read-only, if it requires authentication (beyond optional token), potential rate limits, or data freshness constraints. The num_of_days constraint (1-3) is hinted at but not fully explained.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the purpose, followed by parameter explanations and return format. It is appropriately sized for a 3-param tool with no annotations, though it could be slightly tighter by integrating the parameter details into prose rather than a list.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, an output schema exists, and 0% schema coverage, the description covers purpose, parameters, and return structure adequately. It lacks guidance on error handling or rate limits, but for a simple analysis tool, it provides enough to invoke correctly. The output schema (present) handles return value details, so the description needn't over-explain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It defines project_id as the Microsoft Clarity Project ID, num_of_days as lookback window with allowed values (1,2,3) and default 3, and token as optional API token. This adds substantial meaning beyond the bare schema, though it could clarify token behavior (e.g., required if not set elsewhere).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Analyze JavaScript errors and unhandled exceptions across browsers and operating systems.' It clearly distinguishes the tool from siblings like get_ux_insights or get_frustration_breakdown by naming the exact data domain (JS errors/exceptions).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for analyzing JS errors, but provides no explicit guidance on when to use this tool versus alternatives (e.g., get_frustration_breakdown). It doesn't state exclusions or prerequisites beyond the parameter constraints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve high-level UX insights, frustration rates, and technical health for a Clarity project.
Args: project_id: Microsoft Clarity Project ID (e.g., 'yz5idaioq2'). num_of_days: Lookback window in days (1, 2, or 3 days; defaults to 3). token: Optional Clarity API token. If omitted, uses CLARITY_API_TOKEN environment variable.
Returns: Structured JSON summary of session overview, rage clicks, dead clicks, quick backs, excessive scrolling, JS errors, and quota status.
| Name | Required | Description | Default |
|---|---|---|---|
| token | No | ||
| project_id | Yes | ||
| num_of_days | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It partially meets it: 'Retrieve' implies a non-mutating read, and it discloses auth behavior (token optional, falls back to CLARITY_API_TOKEN) plus the response shape. It does not state rate limits, quota semantics beyond mentioning quota status is returned, or the 1-3 day API constraint rationale.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The Args/Returns structure is front-loaded with purpose and scannable, and each line carries real information. Mild redundancy in restating parameter names and the Returns enumeration duplicating what the output schema already provides, but nothing is bloated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only retrieval tool with three params, the description covers inputs, auth fallback, and output surface, and an output schema exists so return-value detail is largely redundant. The one substantive gap is sibling positioning against get_frustration_breakdown and get_js_errors, which an agent would need to avoid redundant calls.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does: project_id gets a concrete format example ('yz5idaioq2'), num_of_days is constrained to the allowed values (1, 2, or 3 days) with its default restated, and token documents environment-variable fallback behavior that appears nowhere in the schema. All three parameters are meaningfully enriched.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Retrieve ... UX insights') and enumerates the content domains covered (frustration rates, technical health, session overview, rage/dead clicks, JS errors). It does not, however, differentiate itself from siblings like get_frustration_breakdown, get_js_errors, or doctor, whose subject matter clearly overlaps with the listed return categories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance or routing logic. Given sibling tools that cover frustration breakdown and JS errors in depth, an agent cannot tell from this description whether get_ux_insights is the high-level first look or a redundant aggregate — the description never names an alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Load a dynamic skill playbook by name from GitHub (with local fallback).
Args: name: Skill name (e.g., 'ux-triage', 'setup-clarity-token', 'frustration-audit').
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full load, and it does disclose a genuine behavioral trait: fetching from GitHub with a local fallback. However, it omits failure behavior (what happens if the skill is not found), any auth or rate-limit concerns implied by a remote fetch, and whether the result is cached.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core purpose is front-loaded in the first sentence and the argument note is compact. Slight waste in the 'Args:' block, which largely restates the single required parameter, but overall tight.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be explained. The description covers source and fallback adequately, but for a remote-load read tool with no annotations it leaves error/not-found behavior and discovery workflow unspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate for the single 'name' parameter. It provides concrete example values ('ux-triage', 'setup-clarity-token', 'frustration-audit') that convey the naming convention, but no format rules, case sensitivity, or allowed character set.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource (Load a dynamic skill playbook) plus the source mechanism (GitHub with local fallback), which is concrete. It is distinguishable from the sibling skills_list (which presumably enumerates rather than loads), though it doesn't name that sibling explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance is given. It never says to call skills_list first to discover valid names, nor when this differs from related siblings like get_ux_insights or doctor. Usage must be inferred from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List available dynamic skill playbooks bundled with microsoft-clarity-mcp.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden, but the tool is a zero-parameter listing operation where 'list available' already communicates a safe read. It discloses nothing about auth needs, whether results are cached, or how many entries are returned, so it is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence that identifies the action and the resource with no filler or redundant restatement of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description need not explain return values, and a zero-param tool needs little else. The only missing piece is the relationship to skill_read, which is a minor gap given the overall simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the baseline of 4 applies; there is nothing for the description to disambiguate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('List') and a specific resource ('available dynamic skill playbooks bundled with microsoft-clarity-mcp'), which is enough to distinguish it from the singular skill_read sibling. It does not explicitly name or contrast with that sibling, so it falls just short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use, when-not-to-use, or alternative is stated. The presence of a sibling skill_read strongly implies a list-then-read workflow, but the agent must infer that entirely from the names rather than from the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.1check_for_updatesdoctorget_frustration_breakdownget_js_errorsget_ux_insightsskill_readskills_listScored across 7 tools
The three data tools overlap somewhat: get_ux_insights already surfaces rage clicks, dead clicks, quick backs, and JS errors that get_frustration_breakdown and get_js_errors cover in more depth. However, granularity distinguishes them (summary vs. dimension breakdown vs. focused error analysis), and the meta tools (doctor, skills_list, skill_read, check_for_updates) are clearly distinct.
Data tools follow a clean get_<noun> pattern (get_ux_insights, get_frustration_breakdown, get_js_errors), but the rest deviate: skills_list and skill_read use noun_verb, check_for_updates uses verb_for_noun, and doctor is a bare noun. Mixed conventions, though all still readable.
Seven tools is well-scoped for an analytics server: three domain tools for insights/frustration/errors plus four supporting utilities for auth, skills, and updates. Each tool earns its place with no redundancy in count.
Core workflows (overview insights, frustration breakdown, JS error analysis) are covered, along with credential validation and skill playbooks. Minor gaps exist—no raw session/heatmap retrieval, no multi-project or custom-range support beyond the 3-day window—but agents can work around these.
Session replays, JS errors, funnel drop-offs and revenue-loss diagnostics.
Query real user session replay data: tapes, transcripts, error/rage-click filters, alerts.
Session replay and product analytics with an AI judge. Ask about sessions, findings and funnels.
Query your Betterlytics web analytics from AI agents: traffic, funnels, journeys, errors, uptime.
