{"_id":"@microsoft/clarity-mcp-server","_rev":"35-4b1f85a86de4eff65d1652f3fe55c4f8","name":"@microsoft/clarity-mcp-server","dist-tags":{"latest":"2.0.1"},"versions":{"1.0.3":{"name":"@microsoft/clarity-mcp-server","version":"1.0.3","keywords":["clarity","behavior-analytics-tools","heatmaps","session-recordings","insights","analytics","mcp"],"author":"Microsoft","license":"MIT","_id":"@microsoft/clarity-mcp-server@1.0.3","maintainers":[{"name":"microsoft1es","email":"npmjs@microsoft.com"}],"bin":{"clarity-mcp-server":"dist/cli.js"},"dist":{"shasum":"910f713514abc0ef6ce478c0816832681027f3cf","tarball":"https://registry.npmjs.org/@microsoft/clarity-mcp-server/-/clarity-mcp-server-1.0.3.tgz","fileCount":7,"integrity":"sha512-og5ZH6DN0hjOwNaMNSrJfhzakHzk1Z+3XupmW4Rg2zFRCNQb/GfaiArzSvlDwFTdFQMvfuSQ4LjPzyShQrfrDw==","signatures":[{"sig":"MEYCIQDn3rSih0ygqW0QxOfeaFB3gKUr1p07vLa21ZXWh75ZFAIhAO29g074cx7J4d/TLl7PUYNzUGcAFbvyg2pu24klv1eR","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":30454},"main":"dist/index.js","type":"module","_from":"file:M:\\SvcFab\\_App\\MS.Ess.PackageManager.Publisher_App2\\temp\\afc50dfb-cd7a-4bee-b154-99b51acd0aa1\\microsoft-clarity-mcp-server-1.0.3.tgz","scripts":{"dev":"tsc && node dist/index.js","build":"tsc","start":"node dist/index.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"microsoft1es","email":"npmjs@microsoft.com"},"_resolved":"M:\\SvcFab\\_App\\MS.Ess.PackageManager.Publisher_App2\\temp\\afc50dfb-cd7a-4bee-b154-99b51acd0aa1\\microsoft-clarity-mcp-server-1.0.3.tgz","_integrity":"sha512-og5ZH6DN0hjOwNaMNSrJfhzakHzk1Z+3XupmW4Rg2zFRCNQb/GfaiArzSvlDwFTdFQMvfuSQ4LjPzyShQrfrDw==","description":"MCP Server for Microsoft Clarity based on data export API","directories":{},"_nodeVersion":"18.5.0","dependencies":{"zod":"^3.22.4","@modelcontextprotocol/sdk":"^1.10.2"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.3.3","@types/node":"^20.11.0"},"_npmOperationalInternal":{"tmp":"tmp/clarity-mcp-server_1.0.3_1746018863359_0.6676625631921724","host":"s3://npm-registry-packages-npm-production"}},"1.0.4":{"name":"@microsoft/clarity-mcp-server","version":"1.0.4","keywords":["clarity","behavior-analytics-tools","heatmaps","session-recordings","insights","analytics","mcp"],"author":"Microsoft","license":"MIT","_id":"@microsoft/clarity-mcp-server@1.0.4","maintainers":[{"name":"microsoft1es","email":"npmjs@microsoft.com"}],"bin":{"clarity-mcp-server":"dist/cli.js"},"dist":{"shasum":"75e9b2a9862d645705515af37db3979c32e64639","tarball":"https://registry.npmjs.org/@microsoft/clarity-mcp-server/-/clarity-mcp-server-1.0.4.tgz","fileCount":7,"integrity":"sha512-7HnqweD15CD6kSacPXVmpqvwtDh/WZAK5D1lf0XQmcxgqM65+730IkiqfZ4Y6L7WRqApBw61yFPe0t3ls7LZJA==","signatures":[{"sig":"MEYCIQD/Z/1O2Fe01t63GM+nHxrDOkRu7spdRUKkMhn+qL42mgIhAPCWanUfm1jf3vQivbEwJUMXXqSa7ATMU+xpnrVorJQF","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":30241},"main":"dist/index.js","type":"module","_from":"file:M:\\SvcFab\\_App\\MS.Ess.PackageManager.Publisher_App2\\temp\\55a8cb1a-d7a1-4a1c-92f7-c7c5214166de\\microsoft-clarity-mcp-server-1.0.4.tgz","scripts":{"dev":"tsc && node dist/index.js","build":"tsc","start":"node dist/index.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"microsoft1es","email":"npmjs@microsoft.com"},"_resolved":"M:\\SvcFab\\_App\\MS.Ess.PackageManager.Publisher_App2\\temp\\55a8cb1a-d7a1-4a1c-92f7-c7c5214166de\\microsoft-clarity-mcp-server-1.0.4.tgz","_integrity":"sha512-7HnqweD15CD6kSacPXVmpqvwtDh/WZAK5D1lf0XQmcxgqM65+730IkiqfZ4Y6L7WRqApBw61yFPe0t3ls7LZJA==","description":"MCP Server for Microsoft Clarity based on data export API","directories":{},"_nodeVersion":"18.5.0","dependencies":{"zod":"^3.22.4","@modelcontextprotocol/sdk":"^1.10.2"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.3.3","@types/node":"^20.11.0"},"_npmOperationalInternal":{"tmp":"tmp/clarity-mcp-server_1.0.4_1747048444287_0.6089944914123309","host":"s3://npm-registry-packages-npm-production"}},"1.0.5":{"name":"@microsoft/clarity-mcp-server","version":"1.0.5","keywords":["clarity","behavior-analytics-tools","heatmaps","session-recordings","insights","analytics","mcp"],"author":{"name":"Microsoft"},"license":"MIT","_id":"@microsoft/clarity-mcp-server@1.0.5","maintainers":[{"name":"microsoft1es","email":"npmjs@microsoft.com"}],"bin":{"clarity-mcp-server":"dist/cli.js"},"dist":{"shasum":"a2c484a1df8a46438eff2306864e5bc7636afff8","tarball":"https://registry.npmjs.org/@microsoft/clarity-mcp-server/-/clarity-mcp-server-1.0.5.tgz","fileCount":7,"integrity":"sha512-MP0MldUYakM/hMQ5MllaZtN264EpUo0nk0pQ6ggXIhUYBcYTPYFm3tdRTfGcXuCxNgZIAjXYn97xUX5sF+yYTg==","signatures":[{"sig":"MEUCICkACNhQkqYOxY9NCARlxza8Rv++BUcWDYIbsZlz/+YFAiEA4WqIE19GS3RaHw89BkyTk+hrp4eeVgPGU1WCb1s2cIs=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":30257},"main":"dist/index.js","type":"module","_from":"file:M:\\SvcFab\\_App\\MS.Ess.PackageManager.Publisher_App2\\temp\\cf43cbc4-27ad-4b02-9edb-0201003b1dca\\microsoft-clarity-mcp-server-1.0.5.tgz","scripts":{"dev":"tsc && node dist/index.js","build":"tsc","start":"node dist/index.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"microsoft1es","email":"npmjs@microsoft.com"},"_resolved":"M:\\SvcFab\\_App\\MS.Ess.PackageManager.Publisher_App2\\temp\\cf43cbc4-27ad-4b02-9edb-0201003b1dca\\microsoft-clarity-mcp-server-1.0.5.tgz","_integrity":"sha512-MP0MldUYakM/hMQ5MllaZtN264EpUo0nk0pQ6ggXIhUYBcYTPYFm3tdRTfGcXuCxNgZIAjXYn97xUX5sF+yYTg==","description":"MCP Server for Microsoft Clarity based on data export API","directories":{},"_nodeVersion":"18.5.0","dependencies":{"zod":"^3.22.4","@modelcontextprotocol/sdk":"^1.10.2"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.3.3","@types/node":"^20.11.0"},"_npmOperationalInternal":{"tmp":"tmp/clarity-mcp-server_1.0.5_1749734481880_0.1436304393434329","host":"s3://npm-registry-packages-npm-production"}},"2.0.0":{"name":"@microsoft/clarity-mcp-server","version":"2.0.0","keywords":["clarity","behavior-analytics-tools","heatmaps","session-recordings","insights","analytics","mcp","model-context-protocol","ai","agents"],"author":{"name":"Microsoft"},"license":"MIT","_id":"@microsoft/clarity-mcp-server@2.0.0","maintainers":[{"name":"microsoft1es","email":"npmjs@microsoft.com"}],"homepage":"https://clarity.microsoft.com/","bugs":{"url":"https://github.com/microsoft/clarity-mcp-server/issues"},"bin":{"clarity-mcp-server":"dist/cli.js"},"dist":{"shasum":"5ef68b6290b9f721b20ce31c36ed45fa5cbef562","tarball":"https://registry.npmjs.org/@microsoft/clarity-mcp-server/-/clarity-mcp-server-2.0.0.tgz","fileCount":21,"integrity":"sha512-i4dvCBf7X9pSIzR29ntjNkkU7dALZXUVKsjpSjCLjgzV8jtq8Xddvxvfu0EmrbJ6pbSqOFDx9CVwmMGVD+VtMA==","signatures":[{"sig":"MEQCIH4mTOMOYHnNFgyz8LiNJpe85YmkRHIpEGbbDsTXXlARAiA9T10szhLGZJwXC1ljqohfFHXES46h5z3yql06QipybA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":387036},"main":"dist/index.js","type":"module","_from":"file:M:\\SvcFab\\_App\\MS.Ess.PackageManager.Publisher_App1\\temp\\e32db519-9bc4-4746-8c15-1ffced0bab67\\microsoft-clarity-mcp-server-2.0.0.tgz","scripts":{"dev":"tsc && node dist/index.js","build":"tsc","start":"node dist/index.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"microsoft1es","email":"npmjs@microsoft.com"},"_resolved":"M:\\SvcFab\\_App\\MS.Ess.PackageManager.Publisher_App1\\temp\\e32db519-9bc4-4746-8c15-1ffced0bab67\\microsoft-clarity-mcp-server-2.0.0.tgz","_integrity":"sha512-i4dvCBf7X9pSIzR29ntjNkkU7dALZXUVKsjpSjCLjgzV8jtq8Xddvxvfu0EmrbJ6pbSqOFDx9CVwmMGVD+VtMA==","repository":{"url":"git+https://github.com/microsoft/clarity-mcp-server.git","type":"git"},"description":"MCP Server for Microsoft Clarity based on data export API","directories":{},"_nodeVersion":"18.5.0","dependencies":{"zod":"^3.22.4","@modelcontextprotocol/sdk":"^1.10.2"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.3.3","@types/node":"^20.11.0"},"_npmOperationalInternal":{"tmp":"tmp/clarity-mcp-server_2.0.0_1757830867427_0.96161590987647","host":"s3://npm-registry-packages-npm-production"}},"2.0.1":{"name":"@microsoft/clarity-mcp-server","version":"2.0.1","keywords":["clarity","behavior-analytics-tools","heatmaps","session-recordings","insights","analytics","mcp","model-context-protocol","ai","agents"],"author":{"name":"Microsoft"},"license":"MIT","_id":"@microsoft/clarity-mcp-server@2.0.1","maintainers":[{"name":"microsoft1es","email":"npmjs@microsoft.com"}],"homepage":"https://clarity.microsoft.com/","bugs":{"url":"https://github.com/microsoft/clarity-mcp-server/issues"},"bin":{"clarity-mcp-server":"dist/cli.js"},"dist":{"shasum":"b4f852c16b347d4a530548c0fbed334ae926583e","tarball":"https://registry.npmjs.org/@microsoft/clarity-mcp-server/-/clarity-mcp-server-2.0.1.tgz","fileCount":21,"integrity":"sha512-0T4vnPdoY7MDbsHWTQjRknS0ICcHjAZe7xGs7rh0hPhN8g809Ez1G6Kw/iuI+XdJ12CJUTsQSCpTaqRvH9gg6w==","signatures":[{"sig":"MEYCIQCgD79/WYkUS8pFZ6Ff3dTjNLL+6KtpHKDMLCq0BehiQQIhAKWZ42HgcBf6+XsN5G3Ei6KghHu6bU9EpDZsS+ru3Ora","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":391320},"main":"dist/index.js","type":"module","_from":"file:M:\\SvcFab\\_App\\MS.Ess.PackageManager.Publisher_App1\\temp\\c67c3469-762a-4687-9d68-265a892bdfab\\microsoft-clarity-mcp-server-2.0.1.tgz","scripts":{"dev":"tsc && node dist/index.js","build":"tsc","start":"node dist/index.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"microsoft1es","email":"npmjs@microsoft.com"},"_resolved":"M:\\SvcFab\\_App\\MS.Ess.PackageManager.Publisher_App1\\temp\\c67c3469-762a-4687-9d68-265a892bdfab\\microsoft-clarity-mcp-server-2.0.1.tgz","_integrity":"sha512-0T4vnPdoY7MDbsHWTQjRknS0ICcHjAZe7xGs7rh0hPhN8g809Ez1G6Kw/iuI+XdJ12CJUTsQSCpTaqRvH9gg6w==","repository":{"url":"git+https://github.com/microsoft/clarity-mcp-server.git","type":"git"},"description":"MCP Server for Microsoft Clarity based on data export API","directories":{},"_nodeVersion":"18.5.0","dependencies":{"zod":"^3.25.76","@modelcontextprotocol/sdk":"^1.20.2"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.9.3","@types/node":"^20.19.23"},"_npmOperationalInternal":{"tmp":"tmp/clarity-mcp-server_2.0.1_1761632302090_0.2284430915022584","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2025-04-30T09:45:07.222Z","modified":"2026-07-16T15:44:26.934Z","1.0.0":"2025-04-30T09:45:07.536Z","1.0.1":"2025-04-30T12:48:48.743Z","1.0.2":"2025-04-30T13:03:20.586Z","1.0.3":"2025-04-30T13:14:23.539Z","1.0.4":"2025-05-12T11:14:04.465Z","1.0.5":"2025-06-12T13:21:22.055Z","2.0.0":"2025-09-14T06:21:07.702Z","2.0.1":"2025-10-28T06:18:22.362Z"},"bugs":{"url":"https://github.com/microsoft/clarity-mcp-server/issues"},"author":{"name":"Microsoft"},"license":"MIT","homepage":"https://clarity.microsoft.com/","keywords":["clarity","behavior-analytics-tools","heatmaps","session-recordings","insights","analytics","mcp","model-context-protocol","ai","agents"],"repository":{"url":"git+https://github.com/microsoft/clarity-mcp-server.git","type":"git"},"description":"MCP Server for Microsoft Clarity based on data export API","maintainers":[{"email":"npmjs@microsoft.com","name":"microsoft1es"},{"email":"microsoft-oss-publishing@microsoft.com","name":"microsoft-oss-releases"}],"readme":"# Microsoft Clarity MCP Server\r\n\r\nThis is a Model Context Protocol (MCP) server for the Microsoft Clarity.\r\nIt allows you to access your session recordings, project analytics, and documentation from Clarity using Claude for Desktop or other MCP-compatible clients.\r\n\r\n## Key Features\r\n\r\n- **Analytics Data Access**: Query your Microsoft Clarity analytics data including traffic metrics, user behavior insights, and performance statistics\r\n- **Session Recording Retrieval**: Access and analyze session recordings to understand user interactions and identify optimization opportunities\r\n- **Natural Language Querying**: Ask questions in plain English to get insights from your data - no need to learn complex query syntax or API endpoints\r\n- **Flexible Data Filtering**: Filter results by various dimensions such as browser, device, country, and many more\r\n- **Real-Time Data Access**: Fetch the latest analytics data and insights from your Clarity projects on-demand\r\n- **Documentation Integration**: Get quick answers and guidance from Microsoft Clarity documentation directly within your workflow\r\n- **Seamless MCP Integration**: Works natively with Claude for Desktop, Visual Studio Code, and other Model Context Protocol (MCP) compatible clients\r\n\r\n## Setup and Installation\r\n\r\n### Prerequisites\r\n\r\n- Node.js v16 or higher\r\n- A Microsoft Clarity account and API token\r\n- Any MCP-compatible client (Claude for Desktop, etc.)\r\n\r\n### Installation\r\n\r\n#### Option 1: Install via npm (recommended)\r\n\r\nYou can install and run this package directly using npm:\r\n\r\n```bash\r\n# Install globally\r\nnpm install -g @microsoft/clarity-mcp-server\r\n\r\n# Run the server\r\nclarity-mcp-server\r\n```\r\n\r\n#### Option 2: Run with npx without installing\r\n\r\nYou can run the server directly using npx without installing:\r\n\r\n```bash\r\nnpx @microsoft/clarity-mcp-server\r\n```\r\n\r\nWith either option, you can provide your Clarity API token using the `--clarity_api_token` parameter:\r\n\r\n```bash\r\nnpx @microsoft/clarity-mcp-server --clarity_api_token=your-token-here\r\n```\r\n\r\n#### Option 3: Manual Installation\r\n\r\n1. Clone or download this repository\r\n2. Install dependencies:\r\n   ```\r\n   npm install\r\n   ```\r\n3. Build the TypeScript code:\r\n   ```\r\n   npm run build\r\n   ```\r\n4. Run the server:\r\n   ```\r\n   npm run start\r\n   ```\r\n\r\n### Extension/Plugin Installation\r\n\r\n#### Visual Studio Code Extension\r\n\r\n[<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)\r\n\r\nClick the button above to install the Microsoft Clarity MCP server directly in Visual Studio Code.\r\n\r\n#### Claude Desktop Plugin\r\n\r\nInstall from Claude's extension gallery:\r\n\r\n1. Open **Claude Desktop**\r\n2. Navigate to **File → Settings → Extensions**\r\n3. Search for **Microsoft Clarity**\r\n4. Click **Install** to add the extension\r\n5. Configure your **API Token**:\r\n   <br>\r\n   Follow the instructions in the [API Token section](#api-token) to retrieve and set it up correctly.\r\n\r\n## Configuration\r\n\r\nYou can provide the [Clarity data export API](https://learn.microsoft.com/en-us/clarity/setup-and-installation/clarity-data-export-api) token in two ways:\r\n\r\n1. **Command Line Arguments**:\r\n   ```bash\r\n   npx @microsoft/clarity-mcp-server --clarity_api_token=your-token\r\n   ```\r\n\r\n2. **Tool Parameters**:\r\n   <br>\r\n   Provide `token` as a parameter when calling the `get-clarity-data` tool\r\n\r\n## Configuring MCP Clients\r\n\r\n### Generic MCP Client Configuration\r\n\r\nMCP clients typically require configuration to connect to the server. Here's a general example of how to configure an MCP client:\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"@microsoft/clarity-mcp-server\": {\r\n      \"command\": \"npx\",\r\n      \"args\": [\r\n        \"@microsoft/clarity-mcp-server\",\r\n        \"--clarity_api_token=your-api-token-here\"\r\n      ]\r\n    }\r\n  }\r\n}\r\n```\r\n\r\nThe specifics of where and how to add this configuration will depend on your specific MCP client.\r\n\r\n### Claude for Desktop Configuration\r\n\r\nTo configure Claude for Desktop to use this server:\r\n\r\n1. Open your Claude for Desktop configuration file:\r\n   - **Windows**: `%AppData%\\Claude\\claude_desktop_config.json`\r\n   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\r\n2. Add the configuration shown in the generic example above\r\n3. Save the configuration file and restart Claude for Desktop\r\n\r\n## Server Usage\r\n\r\nThe server exposes various tools that you can call from any MCP client.\r\nJust ask naturally and keep each request focused on one thing.\r\n\r\n### Query Analytics Dashboard\r\n- <b>Name:</b> `query-analytics-dashboard`\r\n- <b>Description:</b> Retrieves analytics data and metrics from your project's dashboard using a simplified natural language search query.\r\n- <b>Examples:</b>\r\n  - How many Clarity sessions did we get from Egypt in the past 3 days?\r\n  - What are the most used browsers in my Clarity project?\r\n  - Show me traffic metrics from my Clarity project for the last week\r\n\r\n### List Session Recordings\r\n- <b>Name:</b> `list-session-recordings`\r\n- <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.\r\n- <b>Examples:</b>\r\n  - List the most recent Clarity sessions from mobile devices\r\n  - Show the top 5 Clarity sessions with the highest number of user clicks\r\n  - Get Clarity recordings where users encountered JavaScript errors\r\n\r\n### Query Documentation Resources\r\n- <b>Name:</b> `query-documentation-resources`\r\n- <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.\r\n- <b>Examples:</b>\r\n  - How to track custom events using Microsoft Clarity?\r\n  - How many labels can I add to a recording in Microsoft Clarity?\r\n\r\n## API Token\r\n\r\n### Getting Your API Token\r\n\r\nTo generate an API token:\r\n\r\n1. Go to your Clarity project\r\n2. Select Settings → Data Export → Generate new API token\r\n3. Provide a descriptive name for the token\r\n4. Save the generated token securely\r\n\r\n## Privacy Policy\r\n\r\nFor information about data privacy and usage, please refer to the [Microsoft Clarity Privacy Policy](https://clarity.microsoft.com/privacy).\r\n\r\n## License\r\n\r\nThis project is licensed under the <b>MIT</b> License.\r\n","readmeFilename":"README.md"}