HOWZI DOKUMENTATION

Howzi MCP-Server für Google Analytics 4

Howzi ermöglicht autorisierten Nutzern, Fragen zu ihren Google Analytics 4 (GA4) Properties zu stellen. Der remote MCP-Server liefert historische Berichte, Echtzeitberichte auf Anfrage, Feldsuche, Nutzungsinformationen und gespeicherte Howzi-Dashboards. Velyoo AG betreibt den Dienst.

Howzi greift ausschliesslich lesend auf Google Analytics zu. Das Speichern von Dashboard-Einstellungen ändert die Howzi-Konfiguration des Nutzers, niemals Daten in Google Analytics.

Verbindung

Der Endpunkt erfordert eine Autorisierung. Eine nicht authentifizierte Anfrage kann HTTP 401 mit einer WWW-Authenticate-Challenge zurückgeben, die auf die Protected-Resource-Metadaten verweist. Diese Antwort ist erwartbar. Clients sollten die veröffentlichten OAuth-Discovery-Metadaten verwenden und den Authorization-Code-Flow mit PKCE durchführen. Plattformspezifische Angaben zur Client-Registrierung und mögliche Zugangsdaten werden über den sicheren Onboarding-Prozess der jeweiligen Plattform bereitgestellt, nicht auf dieser öffentlichen Seite.

Der Nutzer meldet sich mit Google bei Howzi an. Google-Anmeldung und Zustimmung zum lesenden Google-Analytics-Zugriff sind von der Howzi-MCP-Autorisierung getrennt. Anschliessend wählt der Nutzer eine GA4-Property, auf die er zugreifen darf. Jeder verbundene Assistent erhält eine eigene Autorisierung für Howzi.

Tools

Die folgende Tabelle erläutert Zweck und Auswirkungen der Tools. Maschinenlesbare Tool-Definitionen (tools.json) herunterladen: Die bereitgestellte Momentaufnahme enthält Tool-Namen, Ein- und Ausgabe-JSON-Schemas sowie Annotationen. Die Datei wurde aus dem Quellcode zusammengestellt und ist kein Nachweis einer Live-Abfrage von tools/list. Clients sollten beim Erstellen von Aufrufen die aktuellen MCP-Tool-Definitionen verwenden.

ToolWichtigste EingabenErgebnis und Auswirkung
get_account_statusKeineLiefert Verbindungsstatus und Status der ausgewählten Property, bei Bedarf mit Einrichtungslink. Lesend.
list_dashboardsKeineListet konfigurierte Property-Dashboards und das Standard-Dashboard des Nutzers. Lesend.
get_dashboard_configurationOptional dashboard_idLiefert gespeicherte KPI-Einstellungen und einen Konfigurationslink. Lesend.
search_ga4_fieldsSuchtext, Feldtyp, optionales Dashboard, Limit, Flag für benutzerdefinierte Felder, BerichtstypLiefert passende GA4-Metrik- und Dimensionsdefinitionen sowie gegebenenfalls Einschränkungen. Lesend.
check_ga4_compatibilityBasisbericht und vorgeschlagene FeldsucheLiefert kompatible oder blockierte Feldergänzungen für einen Bericht. Lesend.
get_report_usageKeineLiefert aktuelles Berichtskontingent, Informationen zur Zurücksetzung und Paging-Limits. Lesend.
run_ga4_reportoperation_id, Berichtsdefinition, optionales DashboardFührt einen historischen GA4-Bericht aus und liefert tatsächliche Daten, Werte, Status sowie Paging- und Datenqualitätsinformationen. Lesend; erfolgreiche Abrufe zählen zum Kontingent.
continue_ga4_reportoperation_id, page_tokenRuft auf Anfrage die nächste Seite eines bestehenden historischen Berichts ab. Lesend; unterliegt Berichts- und Paging-Limits.
run_ga4_realtime_reportoperation_id, Berichtsdefinition, optionales DashboardLiefert eine Echtzeit-Momentaufnahme mit Zeitstempel. Eine Abfrage auf Anfrage, keine kontinuierliche Überwachung. Lesend; erfolgreiche Abrufe zählen zum Kontingent.
get_active_usersoperation_idLiefert aktive Nutzer für die letzten sieben vollständigen Tage in der Zeitzone der ausgewählten Property. Lesend; unterliegt dem Kontingent.
get_dashboardoperation_id, Zeitraum, optionales DashboardLiefert KPI-Ergebnisse des gespeicherten Dashboards. Kompatible MCP-Apps-Hosts können zusätzlich eine interaktive Karte anzeigen. Lesend; Berichtsabruflimits gelten.
refresh_dashboardoperation_id, Zeitraum, optionales DashboardAktualisiert Dashboard-Ergebnisse, ohne gespeicherte Standardwerte zu ändern. Lesend; Berichtsabruflimits gelten.
configure_dashboardOptional dashboard_idÖffnet den Howzi-Dashboard-Editor in kompatiblen Hosts. Das Öffnen speichert keine Änderungen.
preview_dashboardDashboard-EntwurfRuft Werte für einen autorisierten Entwurf ab. Jede erfolgreiche Vorschau verbraucht einen Berichtsabruf. Der Entwurf wird nicht gespeichert.
select_dashboard_propertyeditor_id, property_idWählt eine autorisierte Property für die aktuelle Konfigurationsvorschau. Speichert kein Dashboard, ändert aber die vorübergehende Auswahl im Editor.
save_dashboard_configurationVollständiger Dashboard-EntwurfSchreibend: Speichert ausdrücklich validierte KPI- und Property-Einstellungen im Howzi-Konto des Nutzers. Ändert keine GA4-Daten.
report_dashboard_ui_eventTrace- und Instanzkennungen, Phase, QuelleZeichnet ein begrenztes Diagnoseereignis für eine kompatible Dashboard-Oberfläche auf. Fragt keine GA4-Daten ab und verändert sie nicht.

Einige Dashboard-Tools benötigen einen Host, der die entsprechende MCP-Apps-Schnittstelle unterstützt. Ein Client ohne diese Schnittstelle sollte die Berichts-Tools verwenden und nicht versprechen, dass eine interaktive Karte angezeigt wird.

Berechtigungen und Nutzerkontrolle

Alle GA4-Berichtsanfragen sind auf Properties beschränkt, auf die der authentifizierte Howzi-Nutzer zugreifen darf. Eine vom Aufrufer übergebene Property- oder Dashboard-ID gewährt keinen Zugriff auf die Property eines anderen Nutzers. Google-Analytics-Berechtigungen sind ausschliesslich lesend.

Die Dashboard-Aktion Save schreibt Howzi-Einstellungen. Ein Client sollte dies entsprechend offenlegen und klassifizieren. Der Nutzer sollte das Speichern veranlassen und bestätigen, bevor der Client save_dashboard_configuration aufruft. Berichtsabruf und Dashboard-Konfiguration sind getrennte Aktionen.

Ergebnisse, Limits und Fehler

Howzi Free unterstützt derzeit ein Property-Dashboard, 3–5 gespeicherte KPIs und 40 erfolgreiche Berichtsabrufe pro Tag. Howzi Pro unterstützt mehrere Property-Dashboards, bis zu 9 gespeicherte KPIs und 400 erfolgreiche Berichtsabrufe pro Tag. Das aktuelle Kontingent und Informationen zur Zurücksetzung sind über get_report_usage verfügbar. Google Analytics und Howzi können zusätzliche Anfrage- und Paging-Limits anwenden.

Ein Bericht kann für die ausgewählte Property, Daten, Dimensionen oder Filter keine Daten liefern. Fehlende Daten und nicht verfügbare Werte dürfen nicht als null dargestellt werden. Historische Berichte verwenden abgeschlossene Datumsbereiche in der Zeitzone der Property. Echtzeitwerte sind Momentaufnahmen und können sich ändern. Wird eine Feldkombination nicht unterstützt, sollte der Client die zurückgegebenen Kompatibilitäts- oder Fehlerinformationen nutzen, um die Anfrage anzupassen. Läuft die Autorisierung ab, muss sich der Nutzer erneut verbinden. Clients sollten Hinweise für erneute Versuche oder zur Zurücksetzung befolgen, statt fehlgeschlagene Anfragen wiederholt zu senden.

Datenverarbeitung und Support

Howzi ruft autorisierte GA4-Daten ab, um die Anfrage des Nutzers zu beantworten, und übermittelt relevante Ergebnisse an den verbundenen Assistenten. Dessen Anbieter verarbeitet die Inhalte nach seinen eigenen Nutzungsbedingungen und seiner Datenschutzerklärung. Howzi speichert Kontoverbindungen und Dashboard-Konfigurationen, bietet aber keine gespeicherte GA4-Berichtshistorie. Siehe Howzi-Datenschutzerklärung und Nutzungsbedingungen.

Bei Verbindungs- oder Berichtsproblemen hilft der Howzi-Support. Sende keine Passwörter, OAuth-Codes, Tokens oder ungeschwärzten Analytics-Daten in einer Supportanfrage.