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
- MCP-Endpunkt:
https://mcp.howzi.ai/mcp/ga4 - Transport: Streamable HTTP über HTTPS
- OAuth Protected-Resource-Metadaten:
https://mcp.howzi.ai/.well-known/oauth-protected-resource/mcp/ga4 - OAuth Authorization-Server-Metadaten:
https://mcp.howzi.ai/.well-known/oauth-authorization-server - Angeforderter Howzi-Scope:
mcp.read - OAuth-Ressource:
https://mcp.howzi.ai/mcp/ga4
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.
| Tool | Wichtigste Eingaben | Ergebnis und Auswirkung |
|---|---|---|
get_account_status | Keine | Liefert Verbindungsstatus und Status der ausgewählten Property, bei Bedarf mit Einrichtungslink. Lesend. |
list_dashboards | Keine | Listet konfigurierte Property-Dashboards und das Standard-Dashboard des Nutzers. Lesend. |
get_dashboard_configuration | Optional dashboard_id | Liefert gespeicherte KPI-Einstellungen und einen Konfigurationslink. Lesend. |
search_ga4_fields | Suchtext, Feldtyp, optionales Dashboard, Limit, Flag für benutzerdefinierte Felder, Berichtstyp | Liefert passende GA4-Metrik- und Dimensionsdefinitionen sowie gegebenenfalls Einschränkungen. Lesend. |
check_ga4_compatibility | Basisbericht und vorgeschlagene Feldsuche | Liefert kompatible oder blockierte Feldergänzungen für einen Bericht. Lesend. |
get_report_usage | Keine | Liefert aktuelles Berichtskontingent, Informationen zur Zurücksetzung und Paging-Limits. Lesend. |
run_ga4_report | operation_id, Berichtsdefinition, optionales Dashboard | Fü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_report | operation_id, page_token | Ruft auf Anfrage die nächste Seite eines bestehenden historischen Berichts ab. Lesend; unterliegt Berichts- und Paging-Limits. |
run_ga4_realtime_report | operation_id, Berichtsdefinition, optionales Dashboard | Liefert eine Echtzeit-Momentaufnahme mit Zeitstempel. Eine Abfrage auf Anfrage, keine kontinuierliche Überwachung. Lesend; erfolgreiche Abrufe zählen zum Kontingent. |
get_active_users | operation_id | Liefert aktive Nutzer für die letzten sieben vollständigen Tage in der Zeitzone der ausgewählten Property. Lesend; unterliegt dem Kontingent. |
get_dashboard | operation_id, Zeitraum, optionales Dashboard | Liefert KPI-Ergebnisse des gespeicherten Dashboards. Kompatible MCP-Apps-Hosts können zusätzlich eine interaktive Karte anzeigen. Lesend; Berichtsabruflimits gelten. |
refresh_dashboard | operation_id, Zeitraum, optionales Dashboard | Aktualisiert Dashboard-Ergebnisse, ohne gespeicherte Standardwerte zu ändern. Lesend; Berichtsabruflimits gelten. |
configure_dashboard | Optional dashboard_id | Öffnet den Howzi-Dashboard-Editor in kompatiblen Hosts. Das Öffnen speichert keine Änderungen. |
preview_dashboard | Dashboard-Entwurf | Ruft Werte für einen autorisierten Entwurf ab. Jede erfolgreiche Vorschau verbraucht einen Berichtsabruf. Der Entwurf wird nicht gespeichert. |
select_dashboard_property | editor_id, property_id | Wählt eine autorisierte Property für die aktuelle Konfigurationsvorschau. Speichert kein Dashboard, ändert aber die vorübergehende Auswahl im Editor. |
save_dashboard_configuration | Vollständiger Dashboard-Entwurf | Schreibend: Speichert ausdrücklich validierte KPI- und Property-Einstellungen im Howzi-Konto des Nutzers. Ändert keine GA4-Daten. |
report_dashboard_ui_event | Trace- und Instanzkennungen, Phase, Quelle | Zeichnet 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.