Klaviyo MCP Server verbessert

Ein umfassender Model Context Protocol (MCP)-Server für die Interaktion mit der Klaviyo-API. Diese erweiterte Version bietet erweiterte Analysefunktionen, Leistungsoptimierungen und robuste Fehlerbehandlung bei gleichzeitiger vollständiger Kompatibilität mit dem ursprünglichen MCP-Server.

🌟 Hauptfunktionen

• Erweiterte Analysen und Berichte : Zugriff auf Leistungskennzahlen der Kampagne, aggregierte Daten und detaillierte Einblicke

• Umfassende API-Abdeckung : Unterstützung für alle Klaviyo-API-Endpunkte mit der neuesten Revision (15.06.2024)

• Leistungsoptimierungen : Intelligentes Caching, Ratenbegrenzungshandling und effiziente Datenverarbeitung

• Robuste Fehlerbehandlung : Fallback-Mechanismen, detaillierte Protokollierung und sanfte Degradation

• Einfache Integration : Nahtlose Integration mit Claude und anderen LLMs über das Model Context Protocol

Related MCP server: BolideAI MCP

📊 Analyse- und Berichtsfunktionen

Diese erweiterte Version fügt leistungsstarke Analysefunktionen hinzu, die im Original nicht verfügbar waren:

• Kennzahlen zur Kampagnenleistung : Öffnungsraten, Klickraten, Absprungraten und mehr

• Benutzerdefinierte Metrikaggregation : Aggregieren Sie Metriken nach Zeiträumen, Dimensionen und Messungen

• Umsatzzuordnung : Verfolgen Sie den durch Kampagnen und Flows generierten Umsatz

• Abonnenten-Einblicke : Analysieren Sie Abonnentenwachstum, Engagement und Verhalten

🔧 Technische Verbesserungen

1. Zentralisierte Konfiguration ✅

• Ein zentrales Konfigurationssystem ( src/config.js ) für alle API-Parameter wurde erstellt

• API-Revisionsdatum, gültige Statistiken und andere Parameter leicht konfigurierbar gemacht

• Verhinderung von Inkonsistenzen zwischen verschiedenen Dateien bei Änderungen der API-Parameter

2. Verbessertes Protokollierungssystem ✅

• Implementierung eines robusten Protokollierungssystems mit verschiedenen Protokollebenen (Debug, Info, Warn, Fehler)

• Spezielle Protokollierung für API-Anfragen und -Antworten hinzugefügt

• Maskierung sensibler Daten in Protokollen aus Sicherheitsgründen

• Konfigurierbare Protokollziele und Ausführlichkeit

3. Intelligente Ratenbegrenzung ✅

• Wiederholungslogik für Ratenbegrenzungsfehler hinzugefügt

• Exponentielles Backoff mit Jitter für Wiederholungsversuche implementiert

• Klare Rückmeldung beim Erreichen von Ratenbegrenzungen hinzugefügt

• Priorisierung kritischer Anfragen während der Ratenbegrenzung

4. Leistungs-Caching ✅

• Implementiertes In-Memory-Caching für häufig abgerufene Daten

• Cache-Invalidierung basierend auf TTL (Time-to-Live) hinzugefügt

• Optimierter Cache für verschiedene Datentypen (Metriken, Kampagnen usw.)

• Cache-Statistiken zur Überwachung und Optimierung

5. Fehlerbehandlung und Fallbacks ✅

• Umfassende Fehlerbehandlung für alle API-Interaktionen

• Fallback-Mechanismen für eingeschränkten Betrieb, wenn primäre Anforderungen fehlschlagen

• Detaillierte Fehlermeldungen und Informationen zur Fehlerbehebung

• Vermeidung und Behandlung von JSON-Analysefehlern

🔄 API-Version

Diese erweiterte Version verwendet die Klaviyo API Revision 2024-06-15 , die die neuesten Funktionen und Verbesserungen enthält. Der Server ist durch das zentrale Konfigurationssystem auf Vorwärtskompatibilität mit zukünftigen API-Revisionen ausgelegt.

📋 Namensnennung

Dieses Projekt ist eine erweiterte Version des ursprünglichen Klaviyo MCP-Servers von Matt Coatsworth . Die ursprüngliche Arbeit bildete die Grundlage für diese erweiterte Version.

🚀 Erste Schritte

Voraussetzungen

• Node.js v18 oder höher

• Ein Klaviyo-Konto mit API-Zugriff

• Ein privater API-Schlüssel mit entsprechenden Bereichen (Kampagnen: Lesen, Metriken: Lesen usw.)

Installation

1. Klonen Sie dieses Repository:

   git clone https://github.com/ivan-rivera-projects/Klaviyo-MCP-Server-Enhanced.git
   cd Klaviyo-MCP-Server-Enhanced

2. Installieren Sie Abhängigkeiten:

   npm install

3. Erstellen Sie eine .env Datei basierend auf .env.example :

   cp .env.example .env

4. Bearbeiten Sie die .env Datei, um Ihren Klaviyo-API-Schlüssel hinzuzufügen:

   KLAVIYO_API_KEY=your_private_api_key_here
   LOG_LEVEL=info
   LOG_FILE=/tmp/klaviyo-mcp.log
   LOG_RESPONSES=false
   NODE_ENV=development

Starten des Servers

Starten Sie den Server im Entwicklungsmodus mit automatischem Neuladen:

npm run dev

Für den Produktionseinsatz:

npm start

Testen mit MCP Inspector

Sie können den Server mit dem MCP Inspector testen:

npm run inspect

Dadurch wird eine Weboberfläche geöffnet, in der Sie alle verfügbaren Tools und Ressourcen testen können.

📚 Dokumentation

Ausführliche Informationen zu den Analysefunktionen und API-Parametern finden Sie unter:

• ANALYTICS.md – Umfassende Dokumentation zu Analysefunktionen und -nutzung

• docs/KLAVIYO_API_REFERENCE.md – Referenz für Klaviyo-API-Parameter

🔍 Anwendungsbeispiele

Abrufen von Kennzahlen zur Kampagnenleistung

// Retrieve open rates and click rates for a campaign
get_campaign_metrics({
    id: "01JSQRND0PMH88186NREAJEGGN",
    metrics: ["open_rate", "click_rate", "delivered", "bounce_rate"],
    conversion_metric_id: "VevE7N", // Placed Order metric ID
    start_date: "2025-04-01T00:00:00Z", // Optional: Custom date range
    end_date: "2025-05-01T00:00:00Z"    // Optional: Custom date range
})

Abfragen aggregierter Metriken

// Count placed orders grouped by month
query_metric_aggregates({
    metric_id: "VevE7N", // Placed Order metric ID
    measurement: "count",
    group_by: ["month"],
    timeframe: "last_30_days", // Predefined timeframe
    // Or use custom dates:
    start_date: "2025-01-01T00:00:00Z",
    end_date: "2025-05-01T00:00:00Z"
})

Abrufen einer Zusammenfassung der Kampagnenleistung

// Get a comprehensive summary of campaign performance
get_campaign_performance({
    id: "01JSQRND0PMH88186NREAJEGGN"
})

🛠️ Verfügbare Tools

Analyse und Berichterstattung (Neu in der erweiterten Version)

• get_campaign_metrics : Erhalten Sie Leistungsmetriken für eine bestimmte Kampagne (Öffnungsraten, Klickraten usw.).

• query_metric_aggregates : Abfrage aggregierter Metrikdaten für benutzerdefinierte Analyseberichte

• get_campaign_performance : Erhalten Sie eine umfassende Leistungsübersicht für eine Kampagne

Kampagnen (Erweitert)

• get_campaigns : Holen Sie sich Kampagnen von Klaviyo

• get_campaign : Holen Sie sich eine bestimmte Kampagne von Klaviyo

• get_campaign_message : Erhalten Sie eine bestimmte Kampagnennachricht mit Vorlagendetails

• get_campaign_messages : Alle Nachrichten für eine bestimmte Kampagne abrufen

• get_campaign_recipient_estimation : Ruft die geschätzte Empfängerzahl für eine Kampagne ab

Profile

• get_profiles : Profile von Klaviyo abrufen

• get_profile : Holen Sie sich ein bestimmtes Profil von Klaviyo

• create_profile : Erstellen Sie ein neues Profil in Klaviyo

• update_profile : Aktualisieren Sie ein vorhandenes Profil in Klaviyo

• delete_profile : Löscht ein Profil aus Klaviyo

Listen und Segmente

• get_lists : Listen von Klaviyo abrufen

• get_list : Holen Sie sich eine bestimmte Liste von Klaviyo

• create_list : Erstellen Sie eine neue Liste in Klaviyo

• add_profiles_to_list : Profile zu einer Liste in Klaviyo hinzufügen

• get_segments : Segmente von Klaviyo abrufen

• get_segment : Holen Sie sich ein bestimmtes Segment von Klaviyo

Ereignisse und Kennzahlen

• get_events : Ereignisse von Klaviyo abrufen

• create_event : Erstellen Sie ein neues Ereignis in Klaviyo

• get_metrics : Metriken von Klaviyo abrufen

• get_metric : Holen Sie sich eine bestimmte Metrik von Klaviyo

Flüsse

• get_flows : Flows von Klaviyo abrufen

• get_flow : Holen Sie sich einen bestimmten Flow von Klaviyo

• update_flow_status : Aktualisieren Sie den Status eines Flows in Klaviyo

Inhaltsverwaltung

• get_templates : Vorlagen von Klaviyo abrufen

• get_template : Holen Sie sich eine bestimmte Vorlage von Klaviyo

• create_template : Erstellen Sie eine neue Vorlage in Klaviyo

• get_images : Bilder von Klaviyo abrufen

• get_image : Holen Sie sich ein bestimmtes Bild von Klaviyo

E-Commerce

• get_catalogs : Kataloge von Klaviyo abrufen

• get_catalog_items : Artikel aus einem Katalog in Klaviyo abrufen

• get_catalog_item : Holen Sie sich einen bestimmten Artikel aus einem Katalog in Klaviyo

• get_coupons : Holen Sie sich Gutscheine von Klaviyo

• create_coupon_code : Erstellen Sie einen neuen Gutscheincode in Klaviyo

Weitere Tools

• get_tags : Holen Sie sich Tags von Klaviyo

• create_tag : Erstellen Sie ein neues Tag in Klaviyo

• add_tag_to_resource : Fügen Sie einer Ressource in Klaviyo ein Tag hinzu

• get_webhooks : Holen Sie sich Webhooks von Klaviyo

• create_webhook : Erstellen Sie einen neuen Webhook in Klaviyo

• delete_webhook : Einen Webhook aus Klaviyo löschen

• request_profile_deletion : Fordern Sie die Löschung eines Profils zur Einhaltung des Datenschutzes an

• get_forms : Formulare von Klaviyo abrufen

• get_form : Holen Sie sich ein bestimmtes Formular von Klaviyo

• get_product_reviews : Erhalten Sie Produktbewertungen von Klaviyo

• get_product_review : Holen Sie sich eine spezifische Produktbewertung von Klaviyo

🔗 Verfügbare Ressourcen

• klaviyo://profile/{id} : Informationen zu einem bestimmten Profil abrufen

• klaviyo://list/{id} : Informationen zu einer bestimmten Liste abrufen

• klaviyo://segment/{id} : Informationen zu einem bestimmten Segment abrufen

• klaviyo://campaign/{id} : Informationen zu einer bestimmten Kampagne erhalten

• klaviyo://flow/{id} : Informationen zu einem bestimmten Flow abrufen

• klaviyo://template/{id} : Informationen zu einer bestimmten Vorlage abrufen

• klaviyo://metric/{id} : Informationen zu einer bestimmten Metrik abrufen

• klaviyo://catalog/{id} : Informationen zu einem bestimmten Katalog abrufen

⚠️ Bekannte Probleme und Einschränkungen

• Die Klaviyo-API kann Ratenbegrenzungen für Berichtsendpunkte festlegen

• Bei manchen Metriken kann es zu einer Verzögerung kommen, bevor sie in der API verfügbar sind

• Die Verfügbarkeit historischer Daten kann je nach Ihrem Klaviyo-Plan eingeschränkt sein

• Bei der Verwendung mit Claude Desktop können gelegentlich JSON-Parsing-Warnungen auftreten, die die Funktionalität nicht beeinträchtigen

📝 Lizenz

Dieses Projekt basiert auf dem ursprünglichen Klaviyo MCP Server. Für Lizenzinformationen wenden Sie sich bitte an den ursprünglichen Autor.

👥 Mitwirkende

• Originalwerk von Matt Coatsworth

• Verbesserte Version von Ivan Rivera

🔗 Externe Ressourcen

• Klaviyo API-Dokumentation

• Modellkontextprotokoll

• Claude-Dokumentation