Skip to main content
Glama
Sign In
clarity-mcp

clarity-mcp

by Raffaele86
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote
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

Related MCP server: Influencers Club MCP Server

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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    This server cannot be deployed

    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • Clarity Data Export MCP Server

      Clarity Data Export MCP Serverofficial

      microsoft
      A
      license
      A
      quality
      D
      maintenance
      A Model Context Protocol server that lets you fetch Microsoft Clarity analytics data through Claude for Desktop or other MCP-compatible clients, with support for filtering by dimensions and retrieving various metrics.
      3
      18,913 npm
      139
      MIT

    • mpulse-mcp

      hyoon2007
      F
      license
      A
      quality
      B
      maintenance
      MCP server wrapping the Akamai mPulse Query API v2 to fetch RUM aggregate data (summaries, histograms, per-minute time series) with loss-free numbers for downstream statistical analysis.
      8
      -