Microsoft Clarity Data Export Server

What is Microsoft Clarity Data Export Server about?

Provides a lightweight MCP server that connects to the Microsoft Clarity Data Export API, allowing developers and AI assistants to retrieve recent analytics (1‑3 days) with selectable dimensions and metrics.

How to use Microsoft Clarity Data Export Server?

1. Install – either globally with npm (npm install -g @microsoft/clarity-mcp-server) or run directly with npx:

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

2. Configure an MCP client (e.g., Claude for Desktop) by adding a server entry that invokes the above command.
3. Invoke the get-clarity-data tool from the client, supplying:
   • numOfDays (1‑3)
   • Optional dimensions (up to 3, e.g., Browser, Device, Country)
   • Optional metrics (e.g., Traffic, Scroll Depth)
   • token if not passed via CLI.

Key features of Microsoft Clarity Data Export Server

• Simple CLI/NPX execution with a single --clarity_api_token flag.
• Supports up to three filter dimensions and a variety of metrics.
• Limits responses to 1,000 rows (no pagination) and caps at 10 API calls per day.
• Works out‑of‑the‑box with Claude for Desktop and any MCP‑compatible client.
• Available as a VS Code extension and a Claude Desktop plugin.

Use cases of Microsoft Clarity Data Export Server

• AI‑assisted reporting – ask an LLM to generate a traffic summary for the last 2 days.
• Dashboard automation – pull metrics into custom internal dashboards without writing HTTP code.
• Rapid prototyping – test dimension‑metric combinations directly from a chat interface.
• Developer tooling – embed clarity data retrieval in VS Code extensions or CI scripts.

FAQ from the Microsoft Clarity Data Export Server

Q: How far back can I retrieve data? A: Only the most recent 1‑3 days are supported by the Clarity export API.

Q: How many dimensions can I use? A: Up to three dimensions per request.

Q: What are the request limits? A: A maximum of 10 API calls per project per day.

Q: Can I paginate results? A: No. The server returns at most 1,000 rows per request.

Q: Do I need to set environment variables? A: The token can be supplied via the --clarity_api_token CLI argument or as the token tool parameter.

Microsoft Clarity Data Export MCP Server

This is a Model Context Protocol (MCP) server for the Microsoft Clarity data export API. It allows you to fetch analytics data from Clarity using Claude for Desktop or other MCP-compatible clients.

Features

• Query Microsoft Clarity analytics data through a simple interface
• Filter by up to 3 dimensions (Browser, Device, Country/Region, OS, etc.)
• Retrieve various metrics (Scroll Depth, Engagement Time, Traffic, etc.)
• Seamlessly integrates with Claude for Desktop and other MCP clients

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

Option 1: Install via npm (recommended)

You can install and run this package directly using npm:

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

# Run the server
clarity-mcp-server

Option 2: Run with npx without installing

You can run the server directly using npx without installing:

npx @microsoft/clarity-mcp-server

With either option, you can provide your Clarity API token using the --clarity_api_token parameter:

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

Option 3: Manual Installation

1. Clone or download this repository
2. Install dependencies:

   npm install
   

3. Build the TypeScript code:

   npm run build
   

4. Run the server:

   npm start
   

Extension/Plugin Installation

Visual Studio Code Extension

Click the button above to install the Microsoft Clarity MCP server directly in Visual Studio Code.

Claude Desktop Plugin

Install from Claude's extension gallery:

1. Open Claude Desktop.
2. Navigate to File → Settings → Extensions.
3. Search for Microsoft Clarity MCP Server.
4. Click Install to add the extension.
5. Configure your API Token. Follow the instructions in the API Token section to retrieve and set it up correctly.

Configuration

You can provide the Clarity data export API token in two ways:

1. Command Line Arguments:

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

2. Tool Parameters:

   • Provide token as a parameter when calling the get-clarity-data tool

Configuring MCP Clients

Generic MCP Client Configuration

MCP clients typically require configuration to connect to the server. Here's a general example of how to configure an MCP client:

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

The specifics of where and how to add this configuration will depend on your specific MCP client.

Claude for Desktop Configuration

To configure Claude for Desktop to use this server:

1. Open your Claude for Desktop configuration file:

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

2. Add the configuration shown in the generic example above

3. Save the configuration file and restart Claude for Desktop

Using the Server

When using an MCP client with this server configured, you can ask it to fetch Clarity data. For example:

"Can you fetch my Clarity data for the last day, filtered by Browser and showing Traffic metrics?"

The MCP client will then prompt you to run the get-clarity-data tool, which requires:

• numOfDays: Number of days to retrieve (1-3)
• dimensions: Array of dimensions to filter by (optional)
• metrics: Array of metrics to retrieve (optional)

If you haven't configured your credentials via command-line arguments, you'll also need to provide:

• token: Your Clarity API token

API Token

Getting Your API Token

To generate an API token:

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

Limitations

• Maximum of 10 API requests are allowed per project per day
• Data retrieval is confined to the previous 1 to 3 days
• Maximum of three dimensions can be passed in a single request
• The response is limited to 1,000 rows and can't be paginated

License

MIT