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 |
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
- Vai su clarity.microsoft.com, apri il progetto.
- Settings → Data Export → Generate new API token.
- Dai un nome (4-32 char, no spazi, no
@#$%&*!). - 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 [email protected]
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 [email protected] '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.
