Microsoft Clarity MCP

io.github.surendranb由 GitHub 账号 surendranb 发布v0.1.3更新于 Nov 3, 2026

Microsoft Clarity MCP: behavioral UX analytics, rage clicks, dead clicks, scroll, and JS errors.

发布方自己的服务：Microsoft Learn MCP

已验证STDIO仅桌面开发者工具数据与分析

服务详情

标识符: io.github.surendranb/microsoft-clarity-mcp
传输: STDIO
运行时: Desktop only
信任: Verified
发布于: Oct 29, 2026

安全提示

MCP 服务会接收对话中的工具调用请求，并可能执行外部操作。启用前请先了解该服务能做什么，并只授予它所需的权限。

注册中心已验证此条目所属的 GitHub 账号 surendranb。这并不表明该账号就是产品方。

SourceWeft 的检查只涵盖条目是否完整、端点是否响应；不审查服务器的代码，也不审查其工具的行为。

在 README 中添加徽章

向读者展示该 MCP 服务已收录于 SourceWeft，徽章链接到本页。

[![Listed on SourceWeft](https://sourceweft.com/badge/mcp/io.github.surendranb%2Fmicrosoft-clarity-mcp.svg)](https://sourceweft.com/mcp/io.github.surendranb%2Fmicrosoft-clarity-mcp?utm_source=readme&utm_medium=badge)

概览

AI 生成的概览

本地 MCP 服务器，把 Microsoft Clarity 的行为 UX 数据（暴怒点击、无效点击、快速返回、JS 错误）提供给 AI 助手分析。

可以做什么: 获取 Clarity 项目的高层 UX 洞察：会话数、挫败率、过度滚动与技术健康状况
按 URL、设备、浏览器、操作系统或国家/地区拆分挫败指标（暴怒点击、无效点击、快速返回）
分析各浏览器与操作系统下的 JavaScript 错误和未捕获异常
诊断凭据、项目配置、本地缓存与当日剩余配额
列出并加载内置技能手册，并检查 PyPI 上的新版本
适用场景: 适合让助手基于 Microsoft Clarity 数据排查网页 UX 摩擦和前端错误，例如给问题页面排序或调查 JavaScript 异常，而无需打开 Clarity 后台。
运行要求: 通过 stdio 在本地运行，使用 uvx 或 npx 启动（需 Python 或 Node.js）。需要 Microsoft Clarity 数据导出 API 令牌（环境变量 CLARITY_API_TOKEN）和项目 ID（CLARITY_PROJECT_ID），均在 Clarity 项目设置的 Data Export 中生成。需要访问 Clarity API 的网络；仅支持桌面客户端。

安装前请注意

需要 Clarity API 令牌，该凭据可访问项目分析数据，请勿写入共享配置。Clarity 每个项目每天仅允许 10 次请求，因此响应会缓存在本地 ~/.clarity_mcp/cache.json，配额用尽时可能返回带警告的过期数据。该包默认发送匿名使用遥测，可通过 DO_NOT_TRACK、DISABLE_TELEMETRY 或 CLARITY_TELEMETRY 关闭。

安装

在 SourceWeft 中

打开控制台中的 Microsoft Clarity MCP，将其添加到工作区。
为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照仓库中的启动说明。

README

Microsoft Clarity MCP Server (`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.

1. Quickstart

Run directly without installing via uvx (Python) or npx (Node):

Via Python (`uvx`)

Via Node (`npx`)

2. MCP Client Configuration

Add to your MCP client config (claude_desktop_config.json, cursor.json, or Antigravity/OpenCode):

json

{  "mcpServers": {    "microsoft-clarity": {      "command": "uvx",      "args": ["microsoft-clarity-mcp"],      "env": {        "CLARITY_API_TOKEN": "your_clarity_api_token_here"      }    }  }}

{  "mcpServers": {    "microsoft-clarity": {      "command": "uvx",      "args": ["microsoft-clarity-mcp"],      "env": {        "CLARITY_API_TOKEN": "your_clarity_api_token_here"      }    }  }}

Or using npx:

json

{  "mcpServers": {    "microsoft-clarity": {      "command": "npx",      "args": ["-y", "microsoft-clarity-mcp"],      "env": {        "CLARITY_API_TOKEN": "your_clarity_api_token_here"      }    }  }}

{  "mcpServers": {    "microsoft-clarity": {      "command": "npx",      "args": ["-y", "microsoft-clarity-mcp"],      "env": {        "CLARITY_API_TOKEN": "your_clarity_api_token_here"      }    }  }}

3. Authentication & API Tokens

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.

4. Rate-Limit Defense & Persistent Caching

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.

5. Tools

Tool	Parameters	Description
`get_ux_insights`	`project_id`, `num_of_days=3`, `token`	High-level behavioral friction metrics: session counts, rage clicks, dead clicks, quick backs, excessive scroll, and JS errors.
`get_frustration_breakdown`	`project_id`, `dimension="URL"`, `num_of_days=3`, `token`	Ranks friction severity broken down across URL paths, devices, browsers, operating systems, or countries.
`get_js_errors`	`project_id`, `num_of_days=3`, `token`	JavaScript runtime exceptions and error clicks grouped across browsers and operating systems.
`doctor`	`project_id`, `token`	Diagnostic utility checking token format, cache integrity, and remaining daily API quotas.
`skills_list`	(none)	Lists dynamic skill playbooks bundled with the server.
`skill_read`	`name`	Fetches operational playbooks (e.g. `ux-triage`, `setup-clarity-token`, `frustration-audit`).
`check_for_updates`	(none)	Queries PyPI for newer versions and upgrade commands.

6. Telemetry & Privacy

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.

License

来源：README.md，提交 4b5e001

工具

get_ux_insights

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.

输入参数tokenproject_id必填num_of_days

get_frustration_breakdown

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.

输入参数tokendimensionproject_id必填num_of_days

get_js_errors

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.

输入参数tokenproject_id必填num_of_days

doctor

Validate Microsoft Clarity credentials, project configurations, on-disk cache, and remaining daily request quota.

输入参数tokenproject_id

skills_list

List available dynamic skill playbooks bundled with microsoft-clarity-mcp.

无需输入参数。

skill_read

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必填