MCP Ecommerce

Installation guide

How to install Microsoft Clarity MCP Server

In Claude, ChatGPT, Gemini, Microsoft Copilot, Perplexity, Cursor and Claude Code, with what to check before you start and the first prompts to run.

This is a local server. You run it on your own machine with Node.js, and your MCP client starts it with `npx @microsoft/clarity-mcp-server`. It authenticates with a Clarity Data Export API token passed as `--clarity_api_token=<YOUR_CLARITY_API_TOKEN>`. There is no remote URL or browser sign-in. The server is read-only: it queries dashboard metrics, lists session recordings and searches Clarity documentation.

Have a Clarity project admin or the analytics owner generate the token under their own Clarity account, and name it descriptively so it can be revoked later. Because the server runs locally, the person who installs it should be the one who holds the token. Remote-only clients (ChatGPT, Perplexity, and the web version of Claude.ai) cannot start a local command, and the docs do not cover them.

Microsoft Clarity MCP Server setup guide: Microsoft's MCP documentation page on github.com, shown in a browser frame (analytics MCP server for e-commerce)
Microsoft Clarity MCP Server setup guide preview: Microsoft’s documentation on github.com, captured Oct 13, 2026. The page may have changed since; the link opens the live version.

Before you start

  • Node.js v16 or higher installed, so that npx is available in your terminal
  • A Microsoft Clarity account with access to the project you want to query
  • A Clarity Data Export API token, generated in the project under Settings > Data Export > Generate new API token
  • An MCP-compatible client that can run local commands, such as Claude for Desktop, Cursor, Claude Code or VS Code
  • A secure place to store the token (for example a password manager), since it is shown when generated
How it runs
Local, runs on your machine
Access
Read-only
Server address
Copy it from the vendor documentation

Microsoft Clarity MCP Server in Claude

  1. Generate your token in Clarity: open the project, go to Settings > Data Export, select Generate new API token, give it a descriptive name and store it securely.
  2. Open the Claude for Desktop config file. On macOS it is ~/Library/Application Support/Claude/claude_desktop_config.json. On Windows it is %AppData%\Claude\claude_desktop_config.json.
  3. Add the mcpServers entry from the snippet below and replace your-api-token-here with your token.
  4. Save the file and fully restart Claude for Desktop.
  5. Alternative from the docs: open File > Settings > Extensions, search for Microsoft Clarity, click Install, then set the API token as the docs describe.
  6. The docs cover only Claude for Desktop. Claude.ai on the web cannot run a local command like this one.
claude_desktop_config.json
{
  "mcpServers": {
    "@microsoft/clarity-mcp-server": {
      "command": "npx",
      "args": [
        "@microsoft/clarity-mcp-server",
        "--clarity_api_token=your-api-token-here"
      ]
    }
  }
}

Microsoft Clarity MCP Server in ChatGPT

  1. The documentation does not cover ChatGPT. This server runs locally over a command, not a hosted URL.
  2. ChatGPT connectors in Developer mode expect a remote MCP server URL, and the docs give none for this server.
  3. Unless you host the server behind your own remote endpoint (not described in the docs), use a client that can run local commands instead.
  4. If you need this data in ChatGPT, check the vendor documentation at https://github.com/microsoft/clarity-mcp-server for any newer remote option.

Microsoft Clarity MCP Server in Gemini

  1. The documentation does not cover Gemini. Use Gemini CLI's standard way of adding a local server: an mcpServers entry in its settings file.
  2. Open the Gemini CLI settings JSON file. Take its exact location from the Gemini CLI documentation.
  3. Add the entry from the snippet below, replacing your-api-token-here with your Clarity token.
  4. Save the file and restart Gemini CLI.
  5. Check that the server is listed and that its tools appear before you run any queries.
Gemini CLI settings (mcpServers)
{
  "mcpServers": {
    "@microsoft/clarity-mcp-server": {
      "command": "npx",
      "args": [
        "@microsoft/clarity-mcp-server",
        "--clarity_api_token=your-api-token-here"
      ]
    }
  }
}

Microsoft Clarity MCP Server in Microsoft Copilot

  1. The docs mention Visual Studio Code: they describe a VS Code extension install button for this server. Use it for the quickest setup.
  2. For manual setup in VS Code, create or edit .vscode/mcp.json. This is the standard GitHub Copilot format, and the docs do not show it for this server.
  3. Add a servers entry that runs npx with the args @microsoft/clarity-mcp-server and --clarity_api_token=your-api-token-here, as in the snippet below.
  4. Start the server from the MCP controls in VS Code and enter or confirm your token.
  5. Microsoft Copilot Studio is not covered by the docs, and a local command server is not a fit for it without your own hosting.
.vscode/mcp.json
{
  "servers": {
    "clarity": {
      "command": "npx",
      "args": [
        "@microsoft/clarity-mcp-server",
        "--clarity_api_token=your-api-token-here"
      ]
    }
  }
}

Microsoft Clarity MCP Server in Perplexity

  1. The documentation does not cover Perplexity.
  2. Perplexity desktop app connectors are added through the app's connector settings. Take the exact steps from Perplexity's own documentation.
  3. Only use this server there if the app supports local command servers. If it does, use the command npx with the args @microsoft/clarity-mcp-server and --clarity_api_token=<YOUR_CLARITY_API_TOKEN>.
  4. If the app accepts only a remote URL, this server cannot be added directly, because the docs give no hosted endpoint.

Microsoft Clarity MCP Server in Cursor

  1. The documentation does not cover Cursor. It uses the standard mcpServers JSON format described in the generic example in the docs.
  2. Open Cursor's MCP settings and choose to add a new server. This opens the mcp.json config.
  3. Paste the entry from the snippet below and replace your-api-token-here with your Clarity token.
  4. Save the file and check that the server shows as enabled with its tools listed.
  5. Start a new chat and ask a narrow read-only question.
Cursor mcp.json
{
  "mcpServers": {
    "@microsoft/clarity-mcp-server": {
      "command": "npx",
      "args": [
        "@microsoft/clarity-mcp-server",
        "--clarity_api_token=your-api-token-here"
      ]
    }
  }
}

Microsoft Clarity MCP Server in Claude Code

  1. The documentation does not cover Claude Code. Use its standard claude mcp add command for a local server.
  2. Run the command below in your terminal, replacing your-api-token-here with your Clarity token.
  3. Run claude mcp list to confirm that clarity is registered.
  4. Start claude and ask a narrow read-only question about your Clarity project.
  5. The token ends up in your Claude Code config and shell history, so keep both private.
Terminal
claude mcp add clarity -- npx @microsoft/clarity-mcp-server --clarity_api_token=your-api-token-here

Check that it works

Start with questions that only read data. If these answer from your real account, the connection is good.

  • What are the most used browsers in my Clarity project?
  • Show me traffic metrics from my Clarity project for the last week.
  • How to track custom events using Microsoft Clarity?

Troubleshooting

+The server does not appear in my client after editing the config.

Check that the JSON is valid and that the file is the one your client reads. Claude for Desktop must be fully restarted after saving. Confirm that Node.js v16 or higher is installed and that `npx` works in a terminal. Some clients ignore a config entry with a misplaced comma or bracket.

+Tools load but queries return authentication or empty results.

The token is probably wrong, revoked or from a different project. Regenerate it under `Settings > Data Export > Generate new API token` in the Clarity project and update the `--clarity_api_token` argument. Then compare results against your Clarity dashboard. The docs do not state rate limits beyond those of the Data Export API itself.

+The tool names I see differ from the documentation.

The docs are slightly inconsistent about tool names. They list `query-analytics-dashboard`, `list-session-recordings` and `query-documentation-resources`, and also mention a `get-clarity-data` tool when passing the token as a parameter. Use the tool list your client shows, and keep each request focused on one thing.

Written Oct 13, 2026 from the vendor documentation. Exact menus, addresses and commands change; the official documentation is the source of truth.