Microsoft Clarity MCP Server for Behavioral Analytics

Overview

The Microsoft Clarity MCP Server implements the Model Context Protocol (MCP) to expose Microsoft Clarity analytics and session data to any MCP-compatible client (for example Claude for Desktop or Visual Studio Code). It acts as a lightweight bridge between your Clarity projects and a language-model-enabled toolchain, letting you query metrics, list session recordings, and fetch documentation snippets using natural language instead of low-level API calls.

This server is useful when you want to embed Clarity insights into developer workflows, automate ticket triage based on user behavior, or perform ad-hoc analysis (e.g., “show sessions with JS errors from mobile devices last 7 days”) without writing custom API integration code. It accepts a Clarity API token and exposes a set of tools that MCP clients can invoke directly.

Features

• Access Clarity analytics metrics (traffic, engagement, performance)
• Retrieve session recordings and filter by browser, device, country, URL, and more
• Natural-language querying of analytics and recordings via MCP clients
• Documentation lookups: fetch relevant Clarity docs and troubleshooting guidance
• Filter and sort results by common dimensions (date ranges, devices, cities, error types)
• Works with MCP-capable clients like Claude for Desktop, VS Code, and other integrations
• Quick setup via npm or npx; can be run locally or integrated into IDE extensions

Installation / Configuration

Prerequisites: Node.js v16+ and a Microsoft Clarity account with an API token.

Install and run via npm (global install):

# Install globally
npm install -g @microsoft/clarity-mcp-server

# Run the server
clarity-mcp-server --clarity_api_token=YOUR_CLARITY_TOKEN

Run without installing using npx:

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

Manual (from source):

# Clone
git clone https://github.com/microsoft/clarity-mcp-server.git
cd clarity-mcp-server

# Install deps and build
npm install
npm run build

# Start
npm run start -- --clarity_api_token=YOUR_CLARITY_TOKEN

Passing the API token as a tool parameter (for MCP tool invocations) is also supported. Provide token when calling the server’s tools (depends on the MCP client).

MCP client configuration example (generic):

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

Claude for Desktop configuration paths:

• Windows: %AppData%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Add the JSON snippet above to the mcpServers section and restart the client.

Available Tools

The server exposes a small set of purpose-built tools that MCP clients can call. Below is a concise reference.

Tool usage pattern:

• Keep each request focused (one question per call).
• Use plain English; the MCP server maps natural language to Clarity data queries.
• Include date ranges and filters when you need a narrow result set (e.g., device=mobile, country=IN).

Use Cases

• Debugging a regression: “List recent sessions from users who encountered JavaScript errors on checkout” — inspect session metadata to reproduce or prioritize fixes.
• Product analytics: “Which browsers drove the most sessions last month?” — compare browser share and identify compatibility issues.
• UX optimization: “Show session recordings where users abandoned the signup form” — watch replays to find friction points.
• Documentation lookups: “How do I configure Clarity data export?” — get targeted documentation snippets and setup steps without switching tabs.
• IDE-integrated queries: Run Clarity queries from VS Code to annotate pull requests with recent user behavior or link recordings to bug reports.

Tips for Developers

• Scope queries: include explicit filters (dates, device, URL) to reduce results and speed up responses.
• Combine tools: fetch a list of recordings with list-session-recordings and then open or export selected session IDs for deeper analysis.
• Secure tokens: store your Clarity API token in a secure environment or client configuration, and avoid committing it to source control.
• Client-specific setup: some MCP clients require slightly different configuration formats — consult your client docs for exact placement of mcpServers.

Troubleshooting

• Authentication errors: verify the Clarity API token is valid and has the required permissions for data export.
• Empty results: broaden date ranges or remove restrictive filters to confirm data exists.
• Client connection issues: ensure your MCP client can run npx commands or has permission to execute local MCP servers.

For full reference and source code, see the project repository: https://github.com/microsoft/clarity-mcp-server.