Microsoft Clarity MCP Server

@urdigital/mcp-server-clarity

Um servidor MCP (Model Context Protocol) que expõe a análise comportamental do Microsoft Clarity para Claude, Claude Code e qualquer outro cliente compatível com MCP.

Instalação

Não é necessário instalar — execute diretamente com npx:

   npx -y @urdigital/mcp-server-clarity

Configuração

Obtenha um token no seu projeto Clarity → Configurações → Exportação de Dados → Gerar novo token de API. Os tokens são limitados a um único projeto — você precisa de um token separado por projeto se estiver monitorando vários sites.

Adicione à configuração do seu cliente MCP (por exemplo, o claude_desktop_config.json do Claude Desktop):

   {
     "mcpServers": {
       "clarity": {
         "command": "npx",
         "args": ["-y", "@urdigital/mcp-server-clarity"],
         "env": { "CLARITY_API_TOKEN": "your-project-token" }
       }
     }
   }

Ferramentas

Ferramenta	Descrição
clarity_get_insights	Análise comportamental para o projeto configurado: tráfego, engajamento, profundidade de rolagem e sinais de frustração (cliques de raiva, cliques mortos, cliques de retorno rápido, erros de script)

Comportamento importante, confirmado por testes com um projeto real

A API de Exportação de Dados do Clarity é um endpoint único e estreito, com limitações reais que vale a pena conhecer antes de construir sobre ela:

• Apenas os últimos 1 a 3 dias de dados podem ser recuperados. Não há como consultar dados mais antigos por meio desta API.
• Sem dimensões vs. com dimensões é uma troca, não algo aditivo. Chamar sem dimension1/2/3 retorna um amplo resumo de 16 categorias (tráfego, engajamento, métricas de frustração, além de detalhamentos por Navegador/Dispositivo/SO/País/Título da Página/URL de Referência/Páginas Populares). Especificar qualquer dimensão substitui completamente isso por um conjunto de métricas mais restrito (apenas frustração + engajamento + tráfego), tabulado cruzadamente pela(s) dimensão(ões) fornecida(s). Você obtém profundidade em um eixo ou amplitude em muitos — não ambos na mesma chamada.
• numOfDays é validado; nomes de dimensões não são. Um numOfDays fora do intervalo (qualquer coisa diferente de 1, 2 ou 3) retorna um erro HTTP 400 com corpo vazio — sem mensagem de erro. Um nome de dimensão inválido, por outro lado, retorna HTTP 200 e silenciosamente recorre ao resumo padrão sem dimensão, em vez de gerar erro. Esta ferramenta restringe as entradas de dimensão a um enum estrito dos valores válidos exatamente por esse motivo — é a única proteção real contra um resultado silenciosamente incorreto, já que o próprio Clarity não informa.
• Pequena cota diária de solicitações por projeto (o Clarity não expõe o número exato restante em nenhum lugar da resposta da API) — escolha numOfDays e dimensões deliberadamente, em vez de sondar repetidamente.

Licença

MIT