Skip to content
Back to search

clarity-mcp-server

A Model Context Protocol (MCP) server for Microsoft Clarity

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/microsoft/clarity-mcp-server with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/microsoft/clarity-mcp-server'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/microsoft--clarity-mcp-server/badge.svg)](/listings/microsoft--clarity-mcp-server)

HTML

<a href="/listings/microsoft--clarity-mcp-server"><img src="/api/listings/microsoft--clarity-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

[<img src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install+Server&color=0098FF" alt="Install in VS Code">](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522clarity-server%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522%2540microsoft%252Fclarity-mcp-server%2522%255D%257D)

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**: <br> Follow the instructions in the [API Token section](#api-token) to retrieve and set it up correctly.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 219 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Microsoft Clarity MCP Server
  2. This Model Context Protocol (MCP) server connects Microsoft Clarity to Visual Studio Code, Claude Desktop, and other MCP-compatible clients.
  3. Use natural language to explore analytics, session recordings, AI Visibility insights, and Clarity documentation.
  4. ## Key Features
  5. - **Analytics Data Access**: Query your Microsoft Clarity analytics data including traffic metrics, user behavior insights, and performance statistics
  6. - **Session Recording Retrieval**: Access and analyze session recordings to understand user interactions and identify optimization opportunities
  7. - **AI Visibility Citations**: Query citation overview metrics, top queries, query topics, cited pages, and trends for your verified domain
  8. - **AI Visibility Bot Activity**: Query AI crawler activity, requested paths, content and status-code distributions, trends, scrape-to-referral ratios, and connected CDN providers
  9. - **AI Visibility Topic Insights**: Review topic simulation reports, citation rate, competitive share, and content strengths and opportunities for your verified domain
  10. - **Natural Language Querying**: Ask questions in plain English to get insights from your data - no need to learn complex query syntax or API endpoints
  11. - **Flexible Data Filtering**: Filter results by various dimensions such as browser, device, country, and many more
  12. - **Real-Time Data Access**: Fetch the latest analytics data and insights from your Clarity projects on-demand
  13. - **Documentation Integration**: Get quick answers and guidance from Microsoft Clarity documentation directly within your workflow
  14. - **Seamless MCP Integration**: Works natively with Claude for Desktop, Visual Studio Code, and other Model Context Protocol (MCP) compatible clients
  15. ## Setup and Installation
  16. ### Prerequisites
  17. - Node.js v16 or higher
  18. - A Microsoft Clarity account with admin or member access to at least one project
  19. - An MCP-compatible client, such as Visual Studio Code or Claude Desktop
  20. ### Installation
  21. #### Option 1: Run with npx (recommended)
  22. Configure your MCP client to start the latest package with `npx`:
  23. ```json
  24. {
  25. "mcpServers": {
  26. "microsoft-clarity": {
  27. "command": "npx",
  28. "args": ["-y", "--prefer-online", "@microsoft/clarity-mcp-server@latest"]
  29. }
  30. }
  31. }
  32. ```
  33. This launches `npx -y --prefer-online @microsoft/clarity-mcp-server@latest`. Keep any existing server arguments after the package name.
  34. - `@latest` selects the latest published version.
  35. - `--prefer-online` revalidates package metadata with the registry on each launch while reusing cached package contents when possible; clearing the npm cache is not required.
  36. - `-y` avoids installation prompts.
  37. A running server does not update in place. Restart the MCP server (or its client) to check for and use updates.
  38. #### Option 2: Install globally
  39. ```bash
  40. npm install -g @microsoft/clarity-mcp-server
  41. clarity-mcp-server
  42. ```
  43. #### Option 3: Manual Installation
  44. 1. Clone or download this repository
  45. 2. Install dependencies:
  46. ```bash
  47. npm install
  48. ```
  49. 3. Build the TypeScript code:
  50. ```bash
  51. npm run build
  52. ```
  53. 4. Run the server:
  54. ```bash
  55. npm run start
  56. ```
  57. ### Extension/Plugin Installation
  58. #### Visual Studio Code Extension
  59. [<img src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install+Server&color=0098FF" alt="Install in VS Code">](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522clarity-server%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522--prefer-online%2522%252C%2522%2540microsoft%252Fclarity-mcp-server%2540latest%2522%255D%257D)
  60. Click the button above to install the Microsoft Clarity MCP server directly in Visual Studio Code.
  61. #### Claude Desktop Plugin
  62. Install from Claude's extension gallery:
  63. 1. Open **Claude Desktop**
  64. 2. Navigate to **File → Settings → Customize**
  65. 3. Under **Connectors**, search for **Microsoft Clarity**
  66. 4. Click **Install** to add the extension
  67. ### Quick Start
  68. After the server starts:
  69. 1. Ask your MCP client to **sign in to Microsoft Clarity**.
  70. 2. The server opens the Microsoft Clarity sign-in page in your browser. If it cannot open the browser, it returns a link for you to open.
  71. 3. Complete sign-in in the browser, then return to your MCP client.
  72. 4. The client automatically checks sign-in status without asking you to confirm completion. The server receives the authorization code and exchanges tokens on the browser callback; the client reports any sign-in error or shows the projects your account can access.
  73. 5. Select a default project if you can access more than one, then start asking questions about your Clarity data.
  74. Try these prompts:
  75. - How many Clarity sessions did we get in the past 7 days?
  76. - List the most recent Clarity sessions from mobile devices.
  77. - How do I track custom events using Microsoft Clarity?
  78. ## Configuring MCP Clients
  79. ### Generic MCP Client Configuration
  80. MCP clients typically require configuration to connect to the server. Here's a general example of how to configure an MCP client:
  81. ```json
  82. {
  83. "mcpServers": {
  84. "@microsoft/clarity-mcp-server": {
  85. "command": "npx",
  86. "args": [
  87. "-y",
  88. "--prefer-online",
  89. "@microsoft/clarity-mcp-server@latest"
  90. ]
  91. }
  92. }
  93. }
  94. ```
  95. The specifics of where and how to add this configuration will depend on your specific MCP client.
  96. ### Claude for Desktop Configuration
  97. To configure Claude for Desktop to use this server:
  98. 1. Open your Claude for Desktop configuration file:
  99. - **Windows**: `%AppData%\Claude\claude_desktop_config.json`
  100. - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
  101. 2. Add the token-free configuration shown in the generic example above
  102. 3. Save the configuration file and restart Claude for Desktop
  103. ## Server Usage
  104. The server exposes various tools that you can call from any MCP client.
  105. Just ask naturally and keep each request focused on one thing.
  106. ### Analytics Dashboard
  107. - <b>Names:</b> `query-analytics-dashboard`
  108. - <b>Description:</b> Retrieves analytics data and metrics from your project's dashboard using a simplified natural language search query.
  109. - <b>Examples:</b>
  110. - How many Clarity sessions did we get from Egypt in the past 3 days?
  111. - What are the most used browsers in my Clarity project?
  112. - Show me traffic metrics from my Clarity project for the last week
  113. ### Session Recordings
  114. - <b>Names:</b> `list-session-recordings`
  115. - <b>Description:</b> 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.
  116. - <b>Examples:</b>
  117. - List the most recent Clarity sessions from mobile devices
  118. - Show the top 5 Clarity sessions with the highest number of user clicks
  119. - Get Clarity recordings where users encountered JavaScript errors
  120. ### AI Visibility: Citations
  121. - <b>Names:</b> `get-citation-overview`, `list-citation-queries`, `list-citation-topics`, `list-top-cited-pages`, `get-citation-metric-trends`, `get-citation-item-trends`
  122. - <b>Description:</b> Retrieves AI Visibility citation metrics, AI referred traffic, queries, topics, top cited pages, and trends for the verified domain configured on your Clarity project.
  123. - <b>Examples:</b>
  124. - What is my share of authority for non-branded queries over the last 7 days?
  125. - Which AI queries cite my domain most often this month?
  126. - Show citation trends for my top three cited pages.
  127. ### AI Visibility: Bot Activity
  128. - <b>Names:</b> `get-bot-activity-overview`, `list-ai-crawlers`, `list-bot-path-requests`, `get-bot-activity-distribution`, `get-bot-activity-metric-trends`, `get-bot-activity-item-trends`, `get-ai-crawler-trends`, `get-scrape-to-referral-ratio`, `list-connected-cdn-providers`
  129. - <b>Description:</b> Retrieves read-only Bot Activity analytics for your Clarity project, including AI requests, crawlers, requested paths, content types, page types, HTTP status codes, trends over time, scrape-to-referral ratios, and connected CDN providers. Requires a CDN connected to the project in Clarity.
  130. - <b>Examples:</b>
  131. - Which AI crawlers requested my site most often in the last 7 days?
  132. - Which paths did AI bots request most frequently?
  133. - Show the distribution of AI bot requests by content type.
  134. - How many AI bot requests returned unsuccessful HTTP status codes?
  135. - How has the number of site pages crawled changed week over week?
  136. - Trend the top three crawlers over the last 30 days.
  137. - How many times does OpenAI scrape my site for each visit it sends back?
  138. - Why am I not seeing any bot activity data?
  139. ### AI Visibility: Topic Insights
  140. - <b>Names:</b> `get-topic-insight-constraints`, `list-topic-insights`, `get-topic-insight-report`, `get-topic-insight-status`, `create-topic-insight-report`, `regenerate-topic-insight-report`, `delete-topic-insight`
  141. - <b>Description:</b> Manages AI Visibility Topic Insights for your Clarity project: retrieves validation rules, topics, reports, and generation status; creates and regenerates reports; and deletes topics. Reports include citation rate, competitive share, and content strengths and opportunities. Requires the project's domain to be verified in Clarity. Creating, regenerating and deleting topics requires an OAuth sign-in and sufficient permissions for the project; deletion must be confirmed first.
  142. - <b>Examples:</b>
  143. - Which topics am I tracking in Topic Insights?
  144. - What is my citation rate and competitive share for my top topic?
  145. - What content opportunities does my latest topic report suggest?
  146. ### Documentation Resources
  147. - <b>Names:</b> `query-documentation-resources`
  148. - <b>Description:</b> 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.
  149. - <b>Examples:</b>
  150. - How to track custom events using Microsoft Clarity?
  151. - How many labels can I add to a recording in Microsoft Clarity?
  152. ## Migrating from a Data Export API Token
  153. Data Export API token authentication for the MCP server is being deprecated. Migrate to OAuth sign-in using your Microsoft Clarity account by following these steps:
  154. 1. Remove `--clarity_api_token` from the MCP server arguments and remove any `CLARITY_API_TOKEN` environment variable.
  155. 2. Restart the MCP server.
  156. 3. Ask your MCP client to sign in to Microsoft Clarity.
  157. 4. Complete sign-in and consent in the browser.
  158. 5. The client automatically checks sign-in status; select your default project when prompted.
  159. 6. Delete the old token from **Clarity → Settings → Data Export** after confirming OAuth works for your workflow.
  160. ## Troubleshooting API Failures
  161. For internal server errors (HTTP 5xx), tools include the API's `X-Request-Id` response header when present. Share this request ID with support if the issue persists so they can trace the failed request. Internal error bodies and stack traces are not exposed.
  162. ## Privacy Policy
  163. For information about data privacy and usage, please refer to the [Microsoft Clarity Privacy Policy](https://clarity.microsoft.com/privacy).
  164. ## License
  165. This project is licensed under the <b>MIT</b> License.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.