把 Clarity 接进 AI 助手，
之后在对话框里看行为数据

我自己的站上装着 Clarity，书签栏第三层，一年点开不到十次。不是它没用，热图、录屏、死点击都躺在里面，是每次都要登录、选项目、把日期拨到想看的区间，拨完就不想看了。把它的 MCP 接进 AI 助手之后，这件事变成在对话框里打一句话。功能没变，摩擦没了。

先说两条会劝退人的限制：每个项目每天只能请求 10 次，数据最多回看 3 天。官方文档写死的，没有商量余地。10 次听着还行，真问起来三四轮就见底；3 天意味着周一忘了看，上周的数据就永远看不到了。知道这两条，后面的用法才不会拧着来。

它比 GA4 多看到的那一层

GA4 记录「来了多少人、从哪来、停多久」，Clarity 记录「人在页面上点了哪儿、点到什么程度」。两边的账本不一样。

举个具体的。这个月会话数掉了两成，GA4 能告诉你是自然搜索掉的还是投放掉的，再往下就没了。Clarity 能接着往下指：那个落地页在 iPhone 上，「获取报价」被点了 37 次，一次都没跳转，因为它是张图片，没挂链接。改一行代码的事，但没有这层数据，你只会觉得「这页转化不行」。

它盯的是这些：死点击，点了没反应；愤怒点击，同一个地方连着点好几下；快速返回，点进来马上退出去；还有 JS 报错、滚动深度、参与时长。名字听着专业，其实都是很笨的观察，看的是这个人有没有在这儿卡住。

我也得说清楚它不干什么。没有渠道归因，没有转化事件，没有收入。想知道询盘从哪个渠道来，还得回 GA4。

三个工具，各有各的窄

server 是微软自己维护的，npm 包叫 @microsoft/clarity-mcp-server，现在 2.0.2。接上之后，AI 手上多三个工具：

有个误会要先拆掉：list-session-recordings 返回的是清单，不是视频。哪条会话、哪个页面、点了几次、有没有报错，它列得清楚，视频还得回 Clarity 后台点开看。它替你省的是从二十条里挑三条的时间，不是看录屏的时间。

query-documentation-resources 更像一本随身手册。问「自定义事件怎么埋」，它去翻官方文档摘一段给你，省掉开浏览器搜的工夫。用得不多，但查配置的时候省事。

令牌只出现一次

路径是 Clarity 项目 → 设置 → 数据导出。

页面上就三样东西：一句每天 10 次的提示，一个「生成新的 API 令牌」按钮，一个固定的端点。截图里那条 mcp1 是名字，不是令牌本身。

这里有个坑，第一次配的人多半会踩：令牌内容只在生成那一刻显示一次，页面一关就没了，列表里只留名字。丢了只能删掉重建，旧令牌当场失效。所以别在几个地方共用同一个令牌，换的时候会连着停掉别处。

命名有点规矩，4 到 32 个字符，只能用字母、数字和 - _ . 三个符号，不能有空格，同一个项目里不能重名。另外只有项目管理员能建，普通成员进这个页面看不到按钮。

令牌本身是 JWT，请求时放在 header 里：Authorization: Bearer <token>。它等于这个项目全部数据的读权限。别贴进聊天记录，也别提交到 git。

配置短得有点意外

Node 要 16 以上。然后 npx 直接跑，不用装：

npx @microsoft/clarity-mcp-server --clarity_api_token=你的令牌

第一次会下载包，等几十秒是正常的。常用的话装到本地更稳：npm i -g @microsoft/clarity-mcp-server，之后直接敲 clarity-mcp-server。

写进客户端配置，官方给的写法是这样：

{
  "mcpServers": {
    "@microsoft/clarity-mcp-server": {
      "command": "npx",
      "args": [
        "@microsoft/clarity-mcp-server",
        "--clarity_api_token=你的令牌"
      ]
    }
  }
}

能跑，但令牌在启动参数里，同一台机器上别人 ps 一下就能看见。server 其实也认环境变量，换成这样干净些：

{
  "mcpServers": {
    "clarity": {
      "command": "npx",
      "args": ["@microsoft/clarity-mcp-server"],
      "env": {
        "CLARITY_API_TOKEN": "你的令牌"
      }
    }
  }
}

WorkBuddy 读的是 ~/.workbuddy-ai/mcp.json，改完重启，还要在连接器列表里给这个 server 点一次「信任」，不点不启用。Codex 读 TOML，文件在 ~/.codex/config.toml，同一个 server 换个写法：

[mcp_servers.clarity]
command = "npx"
args = ["@microsoft/clarity-mcp-server"]

[mcp_servers.clarity.env]
CLARITY_API_TOKEN = "你的令牌"

验证不用复杂，问一句「最近一天有多少会话、多少用户」。能返回数字就是通了。报 401 先看令牌有没有多一个空格，再去怀疑别的。

10 次配额，别按「查一下」的思路用

这一段最值钱。10 次听着还行，实际问三四轮就没了，而且按项目算，不按令牌算，多建几个令牌也不会变多。

先看工具说明里的原话：

“The query should be focused on one specific data retrieval or aggregation task. Avoid complex multi-purpose queries. Time ranges should be explicitly specified when possible.”

一次只查一个具体问题，别把好几件事塞进一句话；时间范围尽量写清楚。

GitHub · microsoft/clarity-mcp-server

这句话跟「省着用」看着矛盾，其实是一回事。一次问一个主题，但把这个主题要的维度、时间范围一次说全。省的是来回，不是细节。

另外两个习惯。一是攒着问，固定每周看一次，把这一轮想知道的写在一段话里，别临时起意问一句。二是别让它试错，维度名写错、时间范围没给，它可能重试，重试也扣次数。可用的维度就九个：Browser、Device、Country/Region、OS、Source、Medium、Campaign、Channel、URL。

还有个习惯值得养成：让它把结果存成文件。周报要复用的数字，别下个月再花一次配额查。

只有 3 天，历史得自己存

导出接口的参数 numOfDays 只有 1、2、3 三个值，对应最近 24、48、72 小时。Clarity 后台能按 7 天、30 天看，接口不行。

所以「上周三为什么掉」这种问题，接口答不上来。等你想起要查，数据已经过期了。

想留历史只有一条路：定期拉，自己存。每天或每周跑一次，把返回的 JSON 追加进一个文件。存下来的才是你的。

另外两个细节。返回时间是 UTC，国内看「昨天」要加 8 小时，不然会错开一整天。单次响应最多 1000 行，不能翻页，按 URL 维度问，站大一点就被切掉一半，得加筛选条件或者分几次问。

几个坑，提前知道省事

429 不是网络问题，是当天的 10 次用完了，没有「再加一次」的办法，只能等第二天。

截图里那个 www.clarity.ms/export-data/api/v1/project-live-insights 是数据导出接口的端点，MCP server 走的不是它，而是 clarity.microsoft.com/mcp 下面三个地址，令牌只当身份用。看到 401 别去翻导出接口的文档，先看令牌对不对。

数字跟 GA4 对不上是常态。Clarity 过滤机器人、时间用 UTC、口径也不一样，看趋势就行，别拿两边的绝对数互相校验。

什么时候别接

想盯今天下午的活动效果，10 次配额撑不到晚上，Clarity 后台本身也不是实时工具。这种需求交给 GA4 的实时报表更合适。

想做归因，它没有渠道、转化、收入。想让 AI 替你看录屏，也做不到，它只告诉你哪三条值得看，判断还得自己做。

我现在是周一早上问一次：这周流量和参与时长怎么样，哪些页面死点击最多，有没有带 JS 报错的录屏。看完关掉，下周再来。花十分钟配好，比装着三年没打开过强。