Microsoft Clarity Analytics MCP server for AI agents

Microsoft Clarity MCP Server allows you to access your session recordings, project analytics, and documentation from Microsoft Clarity using Claude for Desktop or other MCP-compatible clients. It lets you query data with natural language, retrieve session recordings, and get documentation answers through a simple interface.

Setup and Installation

Prerequisites

Node.js v16 or higher
A Microsoft Clarity account and API token
Any MCP-compatible client (Claude for Desktop, etc.)

Installation Options

Install via npm (Recommended)

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

# Run the server
clarity-mcp-server

Run with npx without installing

npx @microsoft/clarity-mcp-server

With either option, you can provide your Clarity API token:

npx @microsoft/clarity-mcp-server --clarity_api_token=your-token-here

Manual Installation

Clone or download the repository
Install dependencies:
```
npm install
```
Build the TypeScript code:
```
npm run build
```
Run the server:
```
npm run start
```

Visual Studio Code Extension

Install the Microsoft Clarity MCP server directly in Visual Studio Code using the VS Code installer.

Claude Desktop Plugin

Open Claude Desktop
Navigate to File → Settings → Extensions
Search for Microsoft Clarity
Click Install to add the extension
Configure your API Token

Configuration

Provide your Clarity data export API token in one of these ways:

Command Line Arguments:

npx @microsoft/clarity-mcp-server --clarity_api_token=your-token

Tool Parameters: Provide token as a parameter when calling the get-clarity-data tool

Configuring MCP Clients

Generic MCP Client Configuration

Configure your MCP client with settings similar to:

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

Claude for Desktop Configuration

Open your Claude for Desktop configuration file:
- Windows: %AppData%\Claude\claude_desktop_config.json
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Add the configuration shown in the generic example above
Save the file and restart Claude for Desktop

Using the Server

The server provides several tools you can call from any MCP client using natural language:

Query Analytics Dashboard

Name: query-analytics-dashboard
Description: Retrieves analytics data and metrics using natural language search
Examples:
- "How many Clarity sessions did we get from Egypt in the past 3 days?"
- "What are the most used browsers in my Clarity project?"
- "Show me traffic metrics from my Clarity project for the last week"

List Session Recordings

Name: list-session-recordings
Description: Lists session recordings based on specified filtering criteria
Examples:
- "List the most recent Clarity sessions from mobile devices"
- "Show the top 5 Clarity sessions with the highest number of user clicks"
- "Get Clarity recordings where users encountered JavaScript errors"

Query Documentation Resources

Name: query-documentation-resources
Description: Retrieves snippets from Microsoft Clarity documentation
Examples:
- "How to track custom events using Microsoft Clarity?"
- "How many labels can I add to a recording in Microsoft Clarity?"

Getting Your API Token

To generate a Clarity API token:

Go to your Clarity project
Select Settings → Data Export → Generate new API token
Provide a descriptive name for the token
Save the generated token securely

For more information about data privacy, refer to the Microsoft Clarity Privacy Policy.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "microsoft-clarity-mcp-server" '{"command":"npx","args":["@microsoft/clarity-mcp-server","--clarity_api_token=your-api-token-here"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect