Umami MCP

npx add-mcp 'https://cloud.umami.is/mcp'

@umami/mcp

Serveur Model Context Protocol pour les analyses Umami. Permet à Claude, ChatGPT, Cursor et d'autres clients MCP de répondre à des questions sur votre trafic web à l'aide d'outils en lecture seule qui appellent l'API Umami via @umami/api-client.

Le serveur MCP ne communique jamais avec une base de données ; chaque outil passe par l'API publique et les mêmes contrôles de permissions utilisateur/équipe que l'application web.

Outils

Outil	Objectif
list_websites	Trouver les sites web auxquels vous avez accès (appelez d'abord pour obtenir un websiteId).
get_website_daterange	Dates les plus anciennes et les plus récentes avec des données enregistrées.
get_website_stats	Pages vues, visiteurs, visites, taux de rebond, durée + période précédente.
get_website_traffic	Série temporelle de pages vues/visites par minute, heure, jour, mois ou année.
get_website_metrics	Pages principales, référents, canaux, pays, navigateurs, appareils, UTM, événements.
get_realtime	Visiteurs actifs en ce moment.
get_events	Événements suivis individuels (paginés).
get_event_stats	Totaux d'événements personnalisés + période précédente.
get_event_series	Comptages d'événements personnalisés dans le temps, groupés par nom d'événement.
get_event_properties	Noms de propriétés d'événements personnalisés, ou les valeurs d'une propriété.
get_sessions	Sessions de visiteurs (paginées).
get_session_stats	Totaux au niveau de la session : visiteurs, visites, pages vues, événements, pays.
get_annotations	Notes datées sur la chronologie (lancements, campagnes) pour expliquer les changements.
list_segments	Segments et cohortes enregistrés ; passez les IDs via filters.segment / .cohort.
get_session	Une session avec sa chronologie d'activité et ses propriétés.
list_funnels	Entonnoirs enregistrés avec leurs étapes (obtenez un funnelId pour run_funnel).
run_funnel	Entonnoir de conversion à partir d'un funnelId enregistré ou d'étapes de pages/événements ad hoc.
get_goals	Objectifs enregistrés avec conversions, visiteurs et taux pour une plage.
run_journey	Chemins les plus courants empruntés par les visiteurs.
run_retention	Tableau de rétention de cohorte.
run_attribution	Attribution premier/dernier clic pour une conversion.
get_revenue	Totaux de revenus, séries et répartitions.
get_performance	Core Web Vitals (LCP, INP, CLS, FCP, TTFB) percentiles, tendance, répartition.

Tous les outils sont en lecture seule. Les dates sont au format ISO 8601 ; les résultats sont paginés avec une limite stricte sur la taille des pages.

À distance : Umami Cloud

Connectez-vous à https://cloud.umami.is/mcp en utilisant votre clé API Cloud existante :

Authorization: Bearer api_<your-cloud-api-key>

Les clients qui prennent en charge les en-têtes personnalisés peuvent utiliser x-umami-api-key à la place. Si les deux en-têtes sont fournis, ils doivent contenir la même clé. Utilisez un client qui prend en charge la configuration de clé API ou d'en-tête bearer.

Cloud MCP a les mêmes exigences d'abonnement et les mêmes permissions de site web/équipe que l'API Cloud. Tous les outils appellent la passerelle de l'API Cloud, qui valide la clé et achemine les requêtes vers votre région.

À distance : auto-hébergé

Générez une clé API sous Paramètres → Clés API dans votre instance Umami, puis configurez votre client MCP avec le point de terminaison Streamable HTTP :

https://your-umami.example.com/mcp

Définissez l'en-tête d'autorisation en utilisant votre clé :

Authorization: Bearer umami_<your-api-key>

Utilisez un client qui prend en charge les jetons bearer ou les en-têtes d'autorisation personnalisés. Le point de terminaison accepte les clés API auto-hébergées ; les jetons de connexion navigateur ne sont pas pris en charge. Les outils sont en lecture seule et respectent les permissions utilisateur/équipe existantes du propriétaire de la clé. Révoquez la clé dans Paramètres pour déconnecter l'accès. MCP est désactivé par défaut. Définissez MCP_ENABLED=1 pour activer le point de terminaison.

Local / stdio

{
  "mcpServers": {
    "umami": {
      "command": "npx",
      "args": ["-y", "@umami/mcp"],
      "env": {
        "UMAMI_URL": "https://analytics.example.com",
        "UMAMI_API_TOKEN": "umami_…"
      }
    }
  }
}

Variable	Description
UMAMI_URL	URL de l'instance auto-hébergée (/api est ajouté).
UMAMI_API_URL	URL de base complète de l'API à la place, par ex. https://api.umami.is/v1.
UMAMI_API_TOKEN	Clé API ou jeton de connexion (auto-hébergé).
UMAMI_API_KEY	Clé API Umami Cloud.

Pour Cloud stdio, définissez UMAMI_API_KEY et omettez UMAMI_URL et UMAMI_API_TOKEN :

{
  "mcpServers": {
    "umami": {
      "command": "npx",
      "args": ["-y", "@umami/mcp"],
      "env": { "UMAMI_API_KEY": "api_<your-cloud-api-key>" }
    }
  }
}

Exemples de requêtes

• Affichez mes sites web.
• Combien de visiteurs example.com a-t-il reçus la semaine dernière ?
• Quelles ont été les 10 pages principales ce mois-ci ?
• Comparez le trafic de ce mois avec celui du mois précédent.
• D'où vient le trafic ?
• Quels événements d'inscription se sont produits hier ?
• Affichez les sessions de l'utilisateur abc123.
• Quels plans tarifaires les gens ont-ils sélectionnés dans l'événement de paiement le mois dernier ?
• Combien d'événements d'inscription ont été déclenchés chaque jour cette semaine ?
• Exécutez mon entonnoir de paiement pour le mois dernier.
• Comment nous en sortons-nous par rapport à nos objectifs ce trimestre ?
• Quelles pages ont le pire LCP sur mobile ?
• Que s'est-il passé le jour où le trafic a fortement augmenté ?

Utilisation programmatique

import { UmamiClient } from '@umami/api-client';
import { createUmamiMcpServer } from '@umami/mcp';

const server = createUmamiMcpServer({
  client: new UmamiClient({ baseUrl, token }),
});

createUmamiMcpHttpHandler({ createClient }) renvoie un gestionnaire Streamable HTTP pour l'intégration dans n'importe quel framework web ; l'hôte vérifie le jeton bearer et transmet authInfo.