Build a Custom Microsoft Clarity MCP That Connects to Any AI

Microsoft Clarity gives you free heatmaps, session recordings, and behavioral analytics. The problem is getting that data into the AI tools you already use every day.

Microsoft released an official Clarity MCP Server (@microsoft/clarity-mcp-server) so agents like Claude Desktop, Cursor, and Claude Code can query your analytics in natural language. It works, but it has real constraints. At Apexion Studio we run a custom version that plugs into our own analytics workflow and connects cleanly with multiple AI clients. This post explains the official server, where it falls short, and how you can build (or adapt) a custom one for your own site or clients.

What the Official Clarity MCP Gives You

The official server exposes three tools:

• query-analytics-dashboard — Ask natural-language questions about traffic, scroll depth, engagement time, browsers, countries, etc.
• list-session-recordings — Filter and list session recordings by device, browser, URL, country, clicks, errors, and more.
• query-documentation-resources — Pull snippets from Clarity’s own docs.

You start it with:

npx @microsoft/clarity-mcp-server --clarity_api_token=YOUR_TOKEN

Then add it to any MCP client config (Claude Desktop, Cursor, Claude Code, VS Code, etc.).

Important Limits

Clarity’s Data Export API enforces:

• 10 requests per project per day
• Only the last 1–3 days of data
• Maximum 3 dimensions per request
• Response size capped (no pagination)

These limits are fine for occasional checks. They become frustrating when you want daily reports, historical trends, or to share the same data with multiple AI tools and team members.

Why a Custom MCP Makes Sense

A custom Clarity MCP can:

• Add simple caching so you don’t burn the 10-request daily quota on repeated questions.
• Store daily snapshots locally so you can query older data later (Clarity itself doesn’t keep longer history through the API).
• Expose cleaner, more focused tools tailored to your workflow (e.g. “top pages by rage clicks this week”).
• Run as a long-lived service that multiple AI clients (Claude, Cursor, Grok, internal agents) can call without each person managing a local token and process.
• Add light authentication or project switching so one server can serve several Clarity projects.

At Apexion Studio we use a Clarity integration through our own connector so analytics questions can be answered directly inside AI conversations about the site. The same pattern works for any agency or product team that wants Clarity data available wherever their AI tools live.

How to Build Your Own (High-Level)

You don’t have to start from scratch. Two practical paths:

1. Wrap the official server — Run @microsoft/clarity-mcp-server as a dependency and add a thin layer that caches responses, logs usage, and presents a simpler tool interface.
2. Write a small custom server — Use the official MCP TypeScript SDK (@modelcontextprotocol/sdk) and call the Clarity Data Export API yourself. This gives full control over tool names, parameters, and caching.

Minimal steps for a custom server:

1. Generate a Clarity API token (Project Settings → Data Export).
2. Create a Node/TypeScript project and install the MCP SDK.
3. Define tools that accept natural-language or structured queries and map them to Clarity API calls.
4. Add a simple in-memory or file-based cache keyed by query + date range.
5. (Optional) Persist daily snapshots so historical queries become possible.
6. Configure your AI client to start the server the same way it starts any other local MCP.

Example client config snippet (works with most MCP clients):

{
  "mcpServers": {
    "clarity-custom": {
      "command": "node",
      "args": ["./dist/index.js"],
      "env": {
        "CLARITY_API_TOKEN": "your-token-here"
      }
    }
  }
}

Once it is running, you can ask things like:

• “What were the top pages by engagement time in the last 3 days?”
• “Show me mobile sessions from the US that had rage clicks.”
• “Summarize scroll depth on the pricing page.”

Offering This as a Service

For design and development studios, a lightweight custom Clarity MCP is a useful offering:

• Clients get natural-language access to their own analytics without logging into another dashboard.
• You can pair it with design or conversion recommendations generated by the same AI session.
• It differentiates you from agencies that only deliver static reports.

The official server already proves the concept. A small amount of customization removes the daily quota friction and makes the data available across whatever AI tools your team (or your clients) already use.

Useful Links

• Official docs: https://learn.microsoft.com/en-us/clarity/third-party-integrations/clarity-mcp-server
• GitHub: https://github.com/microsoft/clarity-mcp-server
• Clarity Data Export settings (generate your token there)

If you want help wiring Clarity into your own AI workflow or building a small custom MCP for a client project, the pattern is straightforward once the token and caching layer are in place.

Have you connected Clarity to an AI client yet? What questions do you wish you could ask it?