Skip to main content
Glama
Raffaele86

clarity-mcp

by Raffaele86
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

MCP Clarity — Microsoft Clarity Data Export API

Server MCP per Microsoft Clarity ospitato su CT102, registrato come upstream clarity del mcp-gateway con tag analytics.

Architettura

Voce

Valore

Stack

Python 3.12 + FastMCP (mcp==1.27.0) + Starlette + uvicorn

Porta

8091

Working dir

/opt/clarity-mcp/ (CT102)

Stato persistente

/var/lib/clarity-mcp/{cache.db,quota.json}

Systemd

clarity-mcp.service

Endpoint API

GET https://www.clarity.ms/export-data/api/v1/project-live-insights

Auth

Authorization: Bearer <CLARITY_TOKEN> (uno per progetto)

Quota

10 chiamate/giorno/progetto, reset UTC (hard stop locale a 9)

Tag gateway

analytics

Related MCP server: vturb-mcp

Tool esposti

Tool

Cosa fa

clarity_traffic(project?, days=1, dimension="OS")

Sessions / bot % / pages-per-session per dimensione

clarity_popular_pages(project?, days=1, limit=20)

Top URL per visite

clarity_engagement(project?, days=1, dimension="URL", limit=20)

Engagement time + scroll depth

clarity_dead_clicks(project?, days=1, limit=20)

Top URL con click su elementi non interattivi

clarity_rage_clicks(project?, days=1, limit=20)

Top URL con click ripetuti veloci (frustrazione)

clarity_excessive_scroll(project?, days=1, limit=20)

Top URL con scroll eccessivo

clarity_quickback_clicks(project?, days=1, limit=20)

Top URL con bounce immediato

clarity_script_errors(project?, days=1, limit=20)

JS errors + error clicks per URL

clarity_breakdown(dimension1, project?, days=1, dimension2?, dimension3?)

Raw breakdown libero (power user)

clarity_quota_status()

Quota residua oggi (locale, niente API call)

clarity_list_projects()

Progetti configurati nel server

Cache condivisa: tutti i tool URL-based (popular_pages, dead_clicks, rage_clicks, excessive_scroll, quickback_clicks, script_errors, engagement con dimension=URL) usano la stessa chiave cache → 1 chiamata API alimenta 7 tool.

Configurazione

1. Generare il token Clarity

  1. Vai su clarity.microsoft.com, apri il progetto.

  2. Settings → Data Export → Generate new API token.

  3. Dai un nome (4-32 char, no spazi, no @#$%&*!).

  4. Copia il token (mostrato una sola volta).

Solo gli admin del progetto possono generare token.

2. Variabili .env

Copia .env.example in .env e compila:

PORT=8091
CLARITY_TOKENS={"calcolatorigratis":"eyJhbG..."}
CLARITY_DEFAULT_PROJECT=calcolatorigratis
CLARITY_CACHE_DB_PATH=/var/lib/clarity-mcp/cache.db
CLARITY_QUOTA_PATH=/var/lib/clarity-mcp/quota.json
CLARITY_CACHE_TTL=21600
CLARITY_DAILY_LIMIT=9
CLARITY_WARNING_THRESHOLD=7

Multi-progetto: aggiungi chiavi al JSON, es. {"calcolatorigratis":"...", "tuttoseo":"..."}. Le chiamate prendono project="alias" come primo parametro.

Deploy su CT102

./deploy/install.sh root@192.168.1.107

Lo script: rsync della working dir, crea .venv, installa requirements, crea /var/lib/clarity-mcp, installa il systemd unit e fa restart. Se .env non esiste su CT102, lo copia dall'esempio (poi va compilato con il token).

Avvio manuale (debug locale)

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
PORT=8091 CLARITY_TOKENS='{"test":"<token>"}' python clarity_server.py
curl http://localhost:8091/

Registrazione nel mcp-gateway

Su CT102, append in /etc/mcp-gateway/upstreams.yaml:

- name: clarity
  url: http://127.0.0.1:8091/sse
  tags:
    - analytics

Poi:

systemctl restart mcp-gateway
curl -s https://mcp.calcolatorigratis.com/healthz | grep clarity

Visibile in Claude Code come mcp__mcp-gateway__clarity__*.

Verifica end-to-end

# 1. Service attivo
ssh root@192.168.1.107 'systemctl status clarity-mcp'

# 2. Homepage / health
curl http://192.168.1.107:8091/

# 3. SSE endpoint
curl -H "Accept: text/event-stream" http://192.168.1.107:8091/sse

# 4. Gateway
curl -s https://mcp.calcolatorigratis.com/healthz

# 5. Da Claude Code (sessione con tag analytics caricato)
# → chiamare mcp__mcp-gateway__clarity__clarity_list_projects
# → chiamare mcp__mcp-gateway__clarity__clarity_quota_status
# → chiamare mcp__mcp-gateway__clarity__clarity_traffic

Troubleshooting

Sintomo

Causa

Fix

401 Unauthorized

Token scaduto o non valido

Rigenerare in clarity.microsoft.com → Data Export

403 Forbidden

Token non admin

Solo admin del progetto può generare token Data Export

429 Too Many Requests

Superato 10/giorno (lato API)

Reset mezzanotte UTC, riusa la cache (clarity_quota_status)

Quota esaurita per X oggi

Superato CLARITY_DAILY_LIMIT (lato locale)

Stesso effetto del 429, aspetta reset UTC

Progetto 'X' non configurato

Alias non in CLARITY_TOKENS

Aggiungere {"X":"<token>"} al .env e restart

Tool ritorna (nessun dato)

Niente sessioni nel range

Normale su siti a basso traffico — controllare in dashboard Clarity

Vincoli API ricordare

  • numOfDays ∈ {1, 2, 3} (ultime 24/48/72h, niente date arbitrarie).

  • Max 3 dimensioni per request.

  • Risposta max 1.000 righe, non paginabile.

  • 10 chiamate/giorno/progetto, reset UTC.

  • Dimensioni valide: Browser, Device, Country/Region, OS, Source, Medium, Campaign, Channel, URL.

This server cannot be installed

A
license - permissive license
-
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Raffaele86/clarity-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server