Why Clarity Matters for CRO with Claude

Microsoft Clarity is free, privacy-friendly, and genuinely excellent. It gives you heatmaps, scroll maps, session recordings, and behavioural metrics like rage clicks, dead clicks, quick backs, and excessive scrolling — all without sampling. When Claude can access this data, it can connect “users are leaving this page” with “users are rage-clicking on this element” and “scroll depth drops off at this section” to give you a specific, actionable diagnosis rather than a vague observation.

The limitation is that the official Microsoft Clarity MCP server is configured for a single project. If you manage multiple sites — or if you’ve set up separate Clarity projects for different sections of one site — you hit this wall quickly.

This post covers the practical workaround.

Setting Up the Clarity MCP Server

First, the basic setup. You’ll need your Clarity API token, which you can generate in Clarity → Settings → API. Each project has its own project ID, visible in the Clarity dashboard URL.

Add the Clarity MCP server to your Claude desktop config:

{
  "mcpServers": {
    "google-analytics": { ... },
    "google-search-console": { ... },
    "freecrawl": { ... },
    "microsoft-clarity": {
      "command": "npx",
      "args": ["-y", "@microsoft/clarity-mcp-server"],
      "env": {
        "CLARITY_API_TOKEN": "your_api_token_here",
        "CLARITY_PROJECT_ID": "your_project_id_here"
      }
    }
  }
}

This gets you connected to one project. Now here’s how to handle multiple.

The Multiple Project Workaround

The solution is to register the Clarity MCP server multiple times in your config, once per project, each with a distinct name. Claude treats each named entry as a separate tool set, so it can access all of them simultaneously within the same conversation.

{
  "mcpServers": {
    "clarity-main-site": {
      "command": "npx",
      "args": ["-y", "@microsoft/clarity-mcp-server"],
      "env": {
        "CLARITY_API_TOKEN": "your_api_token_here",
        "CLARITY_PROJECT_ID": "abc123mainsite"
      }
    },
    "clarity-blog": {
      "command": "npx",
      "args": ["-y", "@microsoft/clarity-mcp-server"],
      "env": {
        "CLARITY_API_TOKEN": "your_api_token_here",
        "CLARITY_PROJECT_ID": "def456blog"
      }
    },
    "clarity-landing-pages": {
      "command": "npx",
      "args": ["-y", "@microsoft/clarity-mcp-server"],
      "env": {
        "CLARITY_API_TOKEN": "your_api_token_here",
        "CLARITY_PROJECT_ID": "ghi789lp"
      }
    }
  }
}

The CLARITY_API_TOKEN is the same across all entries — it’s your personal API token. Only the CLARITY_PROJECT_ID changes. You can register as many projects as you need.

Telling Claude Which Project to Use

When you start a session, be explicit about which Clarity project you want Claude to reference. For example: “For this analysis, use the data from clarity-landing-pages. Don’t reference clarity-main-site unless I ask.” Claude will respect this and use the correct tool set throughout the conversation.

You can also ask Claude to compare across projects in a single conversation: “Compare heatmap click patterns from clarity-main-site with clarity-landing-pages for equivalent page types. Are users interacting with the navigation differently?” This is something you simply cannot do in the Clarity interface itself.

What Clarity Data Tells Claude

The Clarity MCP server gives Claude access to analytics dashboard data, session recordings metadata, and heatmap data. The most valuable analyses combine these with your GA4 conversion data:

• “Show me pages where GA4 shows a conversion rate below 1% and Clarity shows a high rage-click rate. What are users frustrated by?”
• “Which pages have a Clarity scroll depth below 50%? Cross-reference with GA4 average session duration to see if people are genuinely disengaged or just converting quickly.”
• “Look at the session recordings for pages where users quick-back. What’s the common pattern — are they bouncing from a specific section, or leaving after interacting with a specific element?”

Keeping Your API Token Secure

Your Clarity API token is sensitive — it gives read access to your behavioural data. Store it in an environment variable rather than directly in the config file if your config file is version-controlled or shared. You can reference environment variables in the config like this: "CLARITY_API_TOKEN": "${CLARITY_API_TOKEN}" and set the variable in your shell profile.

Next up: Part 6 — Setting Up Google Tag Manager MCP for Claude, so Claude can check and fix the tracking that all of this data depends on.