clarity

This MCP server exposes a set of natural-language capable tools to interact with Microsoft Clarity data. You can query analytics dashboards, list and filter session recordings, and fetch relevant documentation snippets directly from Clarity, all through MCP-compatible clients like Claude for Desktop. Use natural language prompts to ask for traffic insights, user behavior metrics, or to retrieve session recordings filtered by device, country, browser, and other dimensions. For example, you can request a summary of last week’s traffic by country, or ask for the top pages users visited in a given project, and the server will translate your request into the appropriate Clarity data calls. In addition to analytics, you can retrieve documentation snippets to guide setup, usage, or troubleshooting directly within your workflow.

Prerequisites:

• Node.js v16 or higher
• A Microsoft Clarity account and API token
• An MCP-compatible client (e.g., Claude for Desktop)

Option 1: Install via npm (recommended)

# Install globally
npm install -g @microsoft/clarity-mcp-server

# Run the server
clarity-mcp-server

Option 2: Run with npx without installing

npx @microsoft/clarity-mcp-server

With either option, provide your Clarity API token using the token parameter:

npx @microsoft/clarity-mcp-server --clarity_api_token=your-token-here

Option 3: Manual Installation

# Clone or download the repository

# Install dependencies
npm install

# Build TypeScript code (if applicable)
npm run build

# Run the server
npm run start

Tips and considerations:

• Export token handling: You can supply the Clarity API token via command-line parameter (--clarity_api_token) or via environment variable CLARITY_API_TOKEN when running the server.
• Client configuration: MCP clients typically require a configuration mapping to your server. Use the generic MCP client example in the README as a starting point and adapt to your environment.
• Environment stability: If running behind a proxy or firewall, ensure API endpoints required by Clarity are accessible and that your token has the necessary permissions.
• Rate limits and pagination: When listing session recordings or querying analytics, consider paging results if the API enforces limits to avoid missing data.
• Security: Treat the API token as a secret. Avoid embedding it in shared configs or logs. Use environment variables where possible in production setups.