Clarity MCP Server

What is Clarity MCP Server about?

Provides a simple interface to query Microsoft Clarity’s data export API, allowing MCP clients to retrieve filtered analytics such as scroll depth, engagement time, and traffic metrics.

How to use Clarity MCP Server?

1. Install – run npm install -g @microsoft/clarity-mcp-server or use npx @microsoft/clarity-mcp-server.
2. Run – start the server with the required token, e.g., npx @microsoft/clarity-mcp-server --clarity_api_token=YOUR_TOKEN.
3. Configure – add the server entry to your MCP client configuration (Claude for Desktop, VS Code extension, etc.).
4. Invoke – use the get-clarity-data tool from the client, supplying numOfDays, optional dimensions, metrics, and the token if not passed on the command line.

Key Features of Clarity MCP Server

• Query Clarity data with up to three dimensions (Browser, Device, Country/Region, OS, …).
• Retrieve a variety of metrics: scroll depth, engagement time, traffic, etc.
• Supports command‑line token provision or tool‑parameter token.
• Works with Claude for Desktop, generic MCP clients, VS Code extension, and other plugins.
• Limits: 10 API calls per project per day, 1‑3 day window, max 1,000 rows per request.

Use Cases of Clarity MCP Server

• Product analytics: Pull recent user interaction data for dashboards or reports.
• AI‑assisted insights: Enable Claude or other LLM assistants to answer data‑driven questions.
• Rapid prototyping: Use the server locally to experiment with Clarity metrics without building custom API calls.
• Team collaboration: Share the server via VS Code extension so all developers can query the same analytics.

FAQ from the Clarity MCP Server

Q: Do I need a Microsoft account? A: Yes, you must have a Clarity project and generate an API token in the project’s Settings → Data Export.

Q: How far back can I retrieve data? A: Only the previous 1 to 3 days are available through the export API.

Q: What if I need more than 1,000 rows? A: The server does not support pagination; you must narrow dimensions or metrics to stay within the limit.

Q: Can I run the server without installing globally? A: Absolutely – npx @microsoft/clarity-mcp-server runs it directly without a global install.

Q: How do I integrate with Claude for Desktop? A: Add the server configuration to claude_desktop_config.json as shown in the README, then restart Claude.

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