This Microsoft Clarity MCP Server provides natural language access to Clarity analytics data, session recordings, and documentation through MCP-compatible clients like Claude Desktop and VS Code.
Key Capabilities:
Query Analytics Dashboard: Retrieve analytics data and metrics using natural language queries, including traffic metrics, user behavior insights, and performance statistics for 1-3 days of historical data
Access Multiple Metrics: Fetch metrics such as Scroll Depth, Engagement Time, Traffic, Popular Pages, Browser usage, Device types, Operating Systems, and Country/Region statistics
Filter by Dimensions: Apply up to 3 dimensions to filter data including Browser, Device, Country/Region, OS, Source, Medium, Campaign, Channel, and URL
List Session Recordings: Browse and filter session recordings by URLs, device types, browser, OS, country, city, and user interactions (e.g., JavaScript errors or high click counts)
Query Documentation: Search Microsoft Clarity documentation for setup guides, features, usage instructions, troubleshooting tips, and integration guidance with step-by-step screenshots
Natural Language Interface: Ask questions in plain English without needing to learn complex API syntax or query languages
Real-Time Data Access: Fetch the latest analytics data and insights from your Clarity projects on-demand
Flexible Authentication: Provide API tokens via command line arguments, environment variables, or tool parameters
Supports configuration with Claude for Desktop on macOS systems, using a specific configuration file path at ~/Library/Application Support/Claude/claude_desktop_config.json.
Runs as a Node.js application, using the Microsoft Clarity data export API to fetch analytics data with customizable filters and metrics.
Available as an npm package for easy installation and execution, with support for providing API credentials through command line arguments.
Built with TypeScript, providing type-safe interaction with the Microsoft Clarity analytics data export API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Clarity Data Export MCP Server show me the top 5 countries by sessions from last week"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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: CUT Clarity MCP Server
Node.js v16 or higher
A Microsoft Clarity account and API token
Any MCP-compatible client (Claude for Desktop, etc.)
You can install and run this package directly using npm:
# Install globally
npm install -g @microsoft/clarity-mcp-server
# Run the server
clarity-mcp-serverYou can run the server directly using npx without installing:
npx @microsoft/clarity-mcp-serverWith 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-hereClone or download this repository
Install dependencies:
npm installBuild the TypeScript code:
npm run buildRun the server:
npm run startClick the button above to install the Microsoft Clarity MCP server directly in Visual Studio Code.
Install from Claude's extension gallery:
Open Claude Desktop
Navigate to File → Settings → Extensions
Search for Microsoft Clarity
Click Install to add the extension
Configure your API Token:
You can provide the Clarity data export API token in two ways:
Command Line Arguments:
npx @microsoft/clarity-mcp-server --clarity_api_token=your-tokenTool Parameters:
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.
To configure Claude for Desktop to use this server:
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 configuration file and restart Claude for Desktop
The server exposes various tools that you can call from any MCP client. Just ask naturally and keep each request focused on one thing.
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
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
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?
To generate an 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 information about data privacy and usage, please refer to the Microsoft Clarity Privacy Policy.
This project is licensed under the MIT License.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| filters | Yes | A 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. | |
| sortBy | No | Sort option for session recordings. Default is SessionStart_DESC (newest first). | SessionStart_DESC |
| count | No | The number of sample session recordings to return. Default is 100. Maximum is 250. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds context by detailing that it lists recordings based on filters and specifies the required date filter format. No contradiction with annotations. Could mention pagination or rate limits, but the schema covers return structure partially.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, concise and front-loaded with the core purpose. No wasted words, and it efficiently communicates the tool's function and key constraint (date format).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (many filters, nested objects) and the absence of an output schema, the description should explain what the listing returns. It does not mention return format or pagination details beyond the count parameter. This gap reduces completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already provides detailed parameter meanings. The description adds minimal extra value beyond a brief overview of filter capabilities. For a tool with such rich schema descriptions, this is adequate but not exceptional.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'Microsoft Clarity session recordings', with explicit mention of filtering. The tool name and description distinguish it from sibling tools like 'clarity_clienti' and 'query-analytics-dashboard'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates when to use the tool (to list recordings with filters) and highlights the required date filter format. However, it does not provide explicit guidance on when not to use it or mention alternatives, which would improve score further.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | A 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint true and destructiveHint false, so safety is clear. The description adds behavioral context about natural language querying and prompting for time ranges, which goes beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise with two focused sentences plus a short note. Information is front-loaded and every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema), the description covers the core behavior and usage guidance adequately. It does not detail return format or error handling, but these are less critical for a natural language query tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the parameter description in the schema largely mirrors the tool description. The description adds minimal extra meaning beyond what the schema already provides, so it meets but does not exceed the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it fetches Microsoft Clarity analytics data using a natural language query. It is specific about the resource and action, but does not explicitly differentiate from sibling tools like clarity_clienti or list-session-recordings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides guidance to focus on one task, avoid complex multi-purpose queries, and specify time ranges. It also instructs to prompt the user if no time range is provided, indicating appropriate usage context. However, it does not compare to alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | A 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds context about the content returned (snippets, screenshots) but does not disclose additional behavioral traits like pagination, rate limits, or response structure beyond what annotations imply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the core purpose and immediately follows with usage guidance. Every word earns its place, with no redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, read-only tool with one parameter and no output schema, the description adequately covers purpose, query guidance, and safety. It could optionally mention the expected return format (e.g., text snippets), but given the annotations and simplicity, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'query' has 100% schema description coverage with a detailed description including examples and guidance for temporal constraints. The description adds value by providing concrete examples and instructing the user to prompt for missing time ranges, exceeding what the schema alone provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves Microsoft Clarity documentation snippets for answering user questions, including specific content types like step-by-step screenshots for setup, features, and troubleshooting. It distinguishes well from sibling tools like query-analytics-dashboard and list-session-recordings, which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides some guidance: queries should be focused on one specific topic and avoid complexity. However, it does not explicitly state when to use this tool versus alternatives, nor does it specify prerequisites or cases where the tool is not appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0get-clarity-datalist-session-recordingsquery-analytics-dashboardquery-documentation-resourcesget-clarity-dataScored across 3 tools
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.
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.
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.
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.
Clamp Analytics MCP server: traffic, revenue, funnels, cohorts, errors, and search, for AI agents.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Analytics for MCP servers. Query your tool calls, first-call success, retries and schema cost.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
