IMPORTANT

Superseded by seo-stack-mcp — the same tools plus GSC, GA4, Bing Webmaster and Microsoft Clarity unified in a single uvx-installable MCP server with local credentials. This repo remains as the remote-SSE variant.

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 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.

clarity-mcp

MCP Clarity — Microsoft Clarity Data Export API

Architettura

Tool esposti

Configurazione

1. Generare il token Clarity

2. Variabili `.env`

Deploy su CT102

Avvio manuale (debug locale)

Registrazione nel mcp-gateway

Verifica end-to-end

Troubleshooting

Vincoli API ricordare

Latest Blog Posts

MCP directory API

MCP Clarity — Microsoft Clarity Data Export API

Architettura

Tool esposti

Configurazione

1. Generare il token Clarity

2. Variabili .env

Deploy su CT102

Avvio manuale (debug locale)

Registrazione nel mcp-gateway

Verifica end-to-end

Troubleshooting

Vincoli API ricordare

Latest Blog Posts

MCP directory API

2. Variabili `.env`