Microsoft Clarity MCP

Microsoft Clarity MCP Server (microsoft-clarity-mcp)

FastMCP 服务，提供 Microsoft Clarity 的 Data Export API，用于行为 UX 分析，包括愤怒点击、无效点击、快速返回、过度滚动和 JavaScript 运行时错误。

作为 Google Analytics 和 Search Console 的配套行为诊断引擎，供 AI Agent 使用。

---

1. 快速开始

无需安装，直接通过 uvx（Python）或 npx（Node）运行：

通过 Python（uvx）

uvx microsoft-clarity-mcp

通过 Node（npx）

npx microsoft-clarity-mcp

---

2. MCP 客户端配置

将以下内容添加到 MCP 客户端配置中（claude_desktop_config.json、cursor.json 或 Antigravity/OpenCode）：

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

或使用 npx：

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

---

3. 身份验证与 API 令牌

Microsoft Clarity 使用静态 JWT Bearer 令牌保护数据导出：

1. 登录 Microsoft Clarity。
2. 打开项目仪表板。
3. 前往 Settings -> Data Export。
4. 点击 Generate new API token（提供一个由 4 到 32 个字母数字字符组成的名称，例如 clarity-agent）。
5. 复制生成的令牌并配置 CLARITY_API_TOKEN。

---

4. 速率限制防护与持久化缓存

• 每日配额：Microsoft Clarity 严格限制每个项目每天 10 次请求。
• 自动缓存：为防止 Agent 循环失控耗尽用户配额，所有响应都会缓存在本地磁盘的 ~/.clarity_mcp/cache.json 中，缓存有效期为 1 小时（可通过 CLARITY_CACHE_TTL 配置）。
• 过期缓存回退：如果达到每日 10 次请求的配额，服务会自动提供过期缓存数据并发出明确警告，确保 Agent 能够继续运行而不会直接崩溃。
• 配额透明度：每个工具响应都包含 calls_used_today、remaining_today 和 daily_limit 元数据。

---

5. 工具

工具	参数	描述
get_ux_insights	project_id、num_of_days=3、token	高层级行为摩擦指标：会话数、愤怒点击、无效点击、快速返回、过度滚动和 JS 错误。
get_frustration_breakdown	project_id、dimension="URL"、num_of_days=3、token	按 URL 路径、设备、浏览器、操作系统或国家/地区对摩擦严重程度进行排名。
get_js_errors	project_id、num_of_days=3、token	按浏览器和操作系统分组的 JavaScript 运行时异常和错误点击。
doctor	project_id、token	诊断工具，用于检查令牌格式、缓存完整性和剩余的每日 API 配额。
skills_list	（无）	列出服务附带的动态技能手册。
skill_read	name	获取操作手册（例如 ux-triage、setup-clarity-token、frustration-audit）。
check_for_updates	（无）	查询 PyPI，检查是否有更新版本及升级命令。

---

6. 遥测与隐私

此软件包包含匿名使用情况遥测，用于确保可靠性并检测不同客户端运行环境中的运行时错误。遥测严格遵循 Schema v2：

• 选择退出：严格遵守 DO_NOT_TRACK=1、DISABLE_TELEMETRY=1 或 CLARITY_TELEMETRY=false。
• 不收集个人身份信息：绝不收集用户 URL、个人身份标识符或身份验证令牌。

---

许可证

MIT License。版权所有 (c) 2026 Surendran B。