Skip to main content
Glama
microsoft

Clarity Data Export MCP Server

Official
by microsoft
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

Microsoft Clarity MCP Server

This is a Model Context Protocol (MCP) server for the Microsoft Clarity. It allows you to access your session recordings, project analytics, and documentation from Clarity using Claude for Desktop or other MCP-compatible clients.

Key Features

  • Analytics Data Access: Query your Microsoft Clarity analytics data including traffic metrics, user behavior insights, and performance statistics

  • Session Recording Retrieval: Access and analyze session recordings to understand user interactions and identify optimization opportunities

  • Natural Language Querying: Ask questions in plain English to get insights from your data - no need to learn complex query syntax or API endpoints

  • Flexible Data Filtering: Filter results by various dimensions such as browser, device, country, and many more

  • Real-Time Data Access: Fetch the latest analytics data and insights from your Clarity projects on-demand

  • Documentation Integration: Get quick answers and guidance from Microsoft Clarity documentation directly within your workflow

  • Seamless MCP Integration: Works natively with Claude for Desktop, Visual Studio Code, and other Model Context Protocol (MCP) compatible clients

Related MCP server: google-analytics-mcp

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 run 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

  4. Click Install to add the extension

  5. Configure your API Token:

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:

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

Server Usage

The server exposes various tools that you can call from any MCP client. Just ask naturally and keep each request focused on one thing.

Query Analytics Dashboard

  • Name: query-analytics-dashboard

  • Description: Retrieves analytics data and metrics from your project's dashboard using a simplified natural language search query.

  • 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 your project's session recordings based on a specified filtering criteria. The filters allow you to narrow down the recordings by various fields such as URLs, device types, browser, OS, country, city, and more.

  • 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 to find answers to user questions including step-by-step screenshots for setup guides, features, usage, troubleshooting, and integration instructions.

  • Examples:

    • How to track custom events using Microsoft Clarity?

    • How many labels can I add to a recording in Microsoft Clarity?

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

Privacy Policy

For information about data privacy and usage, please refer to the Microsoft Clarity Privacy Policy.

License

This project is licensed under the MIT License.

Available Tools

3 tools
list-session-recordingsB
Read-only

List Microsoft Clarity session recordings based on specified filters. The filters allow you to narrow down the recordings by various criteria such as URLs, device types, browser, OS, country, city, and more. The date filter is required and must be in UTC ISO 8601 format.

ParametersJSON Schema
NameRequiredDescriptionDefault
filtersYesA set of filters that can be applied to the Microsoft Clarity to session recordings. This allows you to filter recordings based on various criteria such as URLs, device types, browser, OS, country, city, and more. The date filter is required and must be in UTC ISO 8601 format.
sortByNoSort option for session recordings. Default is SessionStart_DESC (newest first).SessionStart_DESC
countNoThe number of sample session recordings to return. Default is 100. Maximum is 250.

TDQS

B3.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate readOnlyHint=true, destructiveHint=false, and openWorldHint=false, covering safety and scope. The description adds that the tool lists recordings 'based on specified filters' and notes the date filter requirement and format, providing some operational context. However, it doesn't disclose behavioral traits like rate limits, authentication needs, pagination, or error handling, which are relevant for a list operation with complex filtering.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and front-loaded, stating the core purpose in the first sentence. The second sentence elaborates on filter examples, and the third specifies the date filter requirement. Each sentence adds value without redundancy, making it efficient for an agent to parse. A slight improvement could be integrating the date filter note more seamlessly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (3 parameters with nested objects, no output schema) and rich annotations, the description is adequate but incomplete. It covers the basic operation and filter scope but lacks details on output format, pagination, error cases, or integration with siblings. For a list tool with extensive filtering, more contextual guidance would enhance completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema fully documents all parameters. The description mentions filters 'such as URLs, device types, browser, OS, country, city, and more' and specifies that the date filter is required in UTC ISO 8601 format, adding minimal context beyond the schema. This meets the baseline for high schema coverage but doesn't provide significant additional semantic value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'List Microsoft Clarity session recordings based on specified filters.' It includes a specific verb ('List'), resource ('Microsoft Clarity session recordings'), and scope ('based on specified filters'). However, it doesn't explicitly distinguish this tool from its siblings (query-analytics-dashboard, query-documentation-resources), which might have overlapping functionality in the same domain.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus its siblings or alternatives. It mentions that 'The date filter is required,' which is a prerequisite, but offers no context about appropriate use cases, exclusions, or comparisons with other tools in the server. This leaves the agent without clear direction on tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

query-analytics-dashboardA
Read-only

Fetch Microsoft Clarity analytics data using a simplified natural language search query. The query should be focused on one specific data retrieval or aggregation task. Avoid complex multi-purpose queries. Time ranges should be explicitly specified when possible. If no time range is provided, prompt the user to specify one.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesA natural language search query string for filtering and shaping analytics data. The query should be specific and include temporal constraints when available. (e.g., 'Top browsers last 3 days', 'The active time duration for mobile devices in United States last week'). Time ranges should be explicitly specified when possible. If no time range is provided, prompt the user to specify one.

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the agent knows this is a safe, read-only operation with limited scope. The description adds useful context about query constraints (single-task focus, time range importance) and the fallback behavior ('prompt the user to specify one'), which goes beyond annotations. However, it doesn't describe rate limits, authentication needs, or response format details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized with four sentences that each add value: purpose statement, query constraints, time range guidance, and fallback behavior. It's front-loaded with the core functionality. Some minor redundancy with the schema description exists, but overall it's efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the single parameter with 100% schema coverage and annotations covering safety/scope, the description adds reasonable context about query constraints and user prompting. However, with no output schema, the description doesn't explain what data format or structure is returned, which is a gap for an analytics tool. The description is adequate but not comprehensive for this complexity level.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% with one parameter 'query' fully documented in the schema. The description reinforces the same constraints (natural language, specific, include time ranges) but doesn't add significant new semantic information beyond what's already in the schema. The baseline of 3 is appropriate when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'fetch' and resource 'Microsoft Clarity analytics data' with the mechanism 'simplified natural language search query'. It distinguishes from sibling tools like 'list-session-recordings' by focusing on analytics data retrieval rather than recordings or documentation. However, it doesn't explicitly contrast with 'query-documentation-resources' beyond the analytics focus.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool: for 'one specific data retrieval or aggregation task' with 'time ranges explicitly specified'. It warns against 'complex multi-purpose queries'. While it doesn't explicitly name sibling alternatives, it implies this is for analytics queries rather than documentation or recordings. No explicit exclusions are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

query-documentation-resourcesA
Read-only

Retrieve Microsoft Clarity documentation snippets for finding answers to user questions including step-by-step screenshots for setup guides, features, usage, troubleshooting, and integration instructions. The query should be focused on one specific documentation topic or question. Avoid complex multi-purpose queries.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesA natural language search query string for filtering and shaping analytics data. The query should be specific and include temporal constraints when available. (e.g., 'Top browsers last 3 days', 'The active time duration for mobile devices in United States last week'). Time ranges should be explicitly specified when possible. If no time range is provided, prompt the user to specify one.

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, covering safety and scope. The description adds useful context about the types of documentation retrieved (snippets, screenshots, guides) and query constraints (focused, single-topic), which helps the agent understand behavioral traits beyond annotations. However, it does not disclose aspects like rate limits, authentication needs, or response format details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded, starting with the core purpose and followed by specific guidelines. Every sentence adds value (e.g., content types, query focus, avoidance of complexity). It could be slightly more concise by combining some clauses, but overall it's efficient with minimal waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (single parameter, no output schema), the description is reasonably complete. It covers purpose, usage, and behavioral context adequately, though it lacks details on output format or error handling. With annotations providing safety and scope info, and schema covering parameters, the description fills most gaps, but could benefit from mentioning response structure or limitations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with the parameter 'query' fully documented in the schema. The description adds some semantic context by specifying that queries should be 'focused on one specific documentation topic or question' and 'avoid complex multi-purpose queries', which clarifies intent beyond the schema's technical details. However, it does not provide additional syntax or format guidance, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with specific verbs ('retrieve documentation snippets') and resources ('Microsoft Clarity documentation'), distinguishing it from sibling tools like 'query-analytics-dashboard' which handles analytics data rather than documentation. It specifies the content types (step-by-step screenshots, setup guides, features, etc.) and scope (one specific topic/question).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context on when to use this tool ('for finding answers to user questions') and includes explicit usage guidance ('query should be focused on one specific documentation topic or question', 'avoid complex multi-purpose queries'). However, it does not explicitly mention when NOT to use it or name specific alternatives among siblings, though the distinction from 'query-analytics-dashboard' is implied by the content focus.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 4 tool updatesv1.0.0
    • Removedget-clarity-data
    • Addedlist-session-recordings
    • Addedquery-analytics-dashboard
    • Addedquery-documentation-resources
  2. 1 tool update
    • First observedget-clarity-data
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.7/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: list-session-recordings retrieves session data with filters, query-analytics-dashboard fetches analytics via natural language queries, and query-documentation-resources retrieves documentation snippets. There is no overlap in functionality, making it easy for an agent to select the correct tool.

Naming Consistency5/5

All tool names follow a consistent verb-noun pattern with hyphens (list-session-recordings, query-analytics-dashboard, query-documentation-resources). The naming is predictable and readable, with no deviations in style or convention.

Tool Count3/5

With only 3 tools, the server feels thin for a data export domain that might benefit from more granular operations like exporting specific data formats or managing exports. However, the tools cover core areas, so it's borderline but not severely lacking.

Completeness4/5

The tools provide good coverage for listing, querying analytics, and accessing documentation, but there are minor gaps such as missing explicit export or download functionality for data, which could limit agent workflows. Overall, it supports key tasks without major dead ends.

Maintenance

ActivityInactive
ResponsivenessUnresponsive

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • umami-mcp-server

    MurkyPuma
    A
    license
    A
    quality
    C
    maintenance
    An MCP server that gives Claude read access to Umami web analytics, allowing natural language queries for stats, breakdowns, pageview trends, live visitors, and user journeys.
    10
    1
    MIT

  • google-analytics-mcp

    pkidwell22
    A
    license
    Not graded
    quality
    D
    maintenance
    A powerful Model Context Protocol (MCP) server that provides comprehensive Google Analytics 4 (GA4), Google Search Console (GSC), and Google Merchant Center (GMC) integration for Claude Desktop and other MCP clients.
    Apache 2.0

  • clarity-mcp

    Raffaele86
    A
    license
    Not graded
    quality
    C
    maintenance
    MCP server for Microsoft Clarity Data Export API, providing tools to retrieve traffic, popular pages, engagement metrics, and user behavior insights such as dead clicks, rage clicks, and script errors. Supports multiple projects with daily quota management and shared caching.
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/microsoft/clarity-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server