Klaviyo MCP サーバー強化

クラビヨ + MCP APIバージョン Node.js

Klaviyo APIとの連携を可能にする包括的なモデルコンテキストプロトコル（MCP）サーバー。この拡張バージョンは、オリジナルのMCPサーバーとの完全な互換性を維持しながら、高度な分析機能、パフォーマンス最適化、堅牢なエラー処理を提供します。

🌟 主な機能

高度な分析とレポート: キャンペーンのパフォーマンス指標、集計データ、詳細な分析情報にアクセスします
包括的な API カバレッジ: 最新リビジョン (2024-06-15) のすべての Klaviyo API エンドポイントをサポート
パフォーマンスの最適化: インテリジェントなキャッシュ、レート制限の処理、効率的なデータ処理
堅牢なエラー処理: フォールバックメカニズム、詳細なログ記録、そして正常なデグラデーション
簡単な統合: モデルコンテキストプロトコルを介してClaudeや他のLLMとシームレスに統合

Related MCP server: Twilio MCP Server

📊 分析とレポート機能

この拡張バージョンでは、オリジナルにはなかった強力な分析機能が追加されています。

キャンペーンパフォーマンス指標: 開封率、クリック率、直帰率など
カスタムメトリック集計: 期間、ディメンション、測定値ごとにメトリックを集計します
収益帰属: キャンペーンやフローによって生成された収益を追跡します
加入者インサイト: 加入者の増加、エンゲージメント、行動を分析

🔧 技術的な強化

1. 集中設定✅

すべてのAPIパラメータの中央設定システム（ src/config.js ）を作成しました
API の改訂日、有効な統計、その他のパラメータを簡単に設定できるようにしました
APIパラメータが変更された場合に異なるファイル間での不整合を防止

2. 強化されたログシステム✅

さまざまなログレベル（デバッグ、情報、警告、エラー）を備えた堅牢なログシステムを実装しました。
APIリクエストとレスポンスの特別なログ記録を追加しました
セキュリティのためログ内の機密データをマスク
設定可能なログ出力先と詳細度

3. インテリジェントなレート制限✅

レート制限エラーの再試行ロジックを追加しました
再試行時にジッターを伴う指数バックオフを実装しました
レート制限に遭遇したときに明確なフィードバックを追加しました
レート制限中に重要なリクエストを優先する

4. パフォーマンスキャッシュ✅

頻繁にアクセスされるデータに対してメモリ内キャッシュを実装
TTL（生存時間）に基づくキャッシュ無効化を追加
さまざまなデータタイプ (メトリック、キャンペーンなど) に合わせて最適化されたキャッシュ
監視と最適化のためのキャッシュ統計

5. エラー処理とフォールバック✅

すべてのAPIインタラクションに対する包括的なエラー処理
プライマリリクエストが失敗した場合の、パフォーマンス低下時のフォールバックメカニズム
詳細なエラーメッセージとトラブルシューティング情報
JSON解析エラーの防止と処理

🔄 APIバージョン

この拡張バージョンは、最新の機能と改善を含むKlaviyo APIリビジョン2024-06-15を使用しています。サーバーは、集中管理された設定システムを通じて、将来のAPIリビジョンとの互換性を維持するように設計されています。

📋 帰属表示

このプロジェクトは、 Matt Coatsworth氏が作成したオリジナルのKlaviyo MCPサーバーの拡張版です。この拡張版の基盤は、オリジナルの作業に基づいています。

🚀 はじめに

前提条件

Node.js v18以上
APIアクセス可能なKlaviyoアカウント
適切なスコープ (campaigns:read、metrics:read など) を持つプライベート API キー

インストール

このリポジトリをクローンします:
git clone https://github.com/ivan-rivera-projects/Klaviyo-MCP-Server-Enhanced.git cd Klaviyo-MCP-Server-Enhanced
依存関係をインストールします:
npm install
.env.exampleに基づいて.envファイルを作成します。
cp .env.example .env
.envファイルを編集して、Klaviyo API キーを追加します。
KLAVIYO_API_KEY=your_private_api_key_here LOG_LEVEL=info LOG_FILE=/tmp/klaviyo-mcp.log LOG_RESPONSES=false NODE_ENV=development

サーバーの起動

自動リロード付きの開発モードでサーバーを起動します。

npm run dev

生産用途の場合:

npm start

MCP Inspectorによるテスト

MCP Inspector を使用してサーバーをテストできます。

npm run inspect

これにより、利用可能なすべてのツールとリソースをテストできる Web インターフェイスが開きます。

📚 ドキュメント

分析機能と API パラメータの詳細については、以下を参照してください。

ANALYTICS.md - 分析機能と使用方法に関する包括的なドキュメント
docs/KLAVIYO_API_REFERENCE.md - Klaviyo APIパラメータのリファレンス

🔍 使用例

キャンペーンパフォーマンス指標の取得

// 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 })

集計されたメトリックのクエリ

// 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" })

キャンペーンパフォーマンスサマリーの取得

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

🛠️ 利用可能なツール

分析とレポート（拡張バージョンの新機能）

get_campaign_metrics : 特定のキャンペーンのパフォーマンス指標 (開封率、クリック率など) を取得します。
query_metric_aggregates : カスタム分析レポート用に集計されたメトリックデータをクエリする
get_campaign_performance : キャンペーンの包括的なパフォーマンス概要を取得します

キャンペーン（拡張）

get_campaigns : Klaviyoからキャンペーンを取得する
get_campaign : Klaviyoから特定のキャンペーンを取得する
get_campaign_message : テンプレートの詳細を含む特定のキャンペーンメッセージを取得します
get_campaign_messages : 特定のキャンペーンのすべてのメッセージを取得する
get_campaign_recipient_estimation : キャンペーンの推定受信者数を取得する

プロフィール

get_profiles : Klaviyoからプロファイルを取得する
get_profile : Klaviyoから特定のプロファイルを取得する
create_profile : Klaviyoで新しいプロフィールを作成する
update_profile : Klaviyo の既存のプロフィールを更新する
delete_profile : Klaviyoからプロフィールを削除する

リストとセグメント

get_lists : Klaviyoからリストを取得する
get_list : Klaviyoから特定のリストを取得する
create_list : Klaviyo で新しいリストを作成する
add_profiles_to_list : Klaviyo のリストにプロフィールを追加する
get_segments : Klaviyoからセグメントを取得する
get_segment : Klaviyoから特定のセグメントを取得する

イベントとメトリクス

get_events : Klaviyoからイベントを取得する
create_event : Klaviyoで新しいイベントを作成する
get_metrics : Klaviyoからメトリクスを取得する
get_metric : Klaviyoから特定のメトリックを取得する

フロー

get_flows : Klaviyoからフローを取得する
get_flow : Klaviyoから特定のフローを取得する
update_flow_status : Klaviyo のフローのステータスを更新する

コンテンツ管理

get_templates : Klaviyoからテンプレートを取得する
get_template : Klaviyoから特定のテンプレートを取得する
create_template : Klaviyo で新しいテンプレートを作成する
get_images : Klaviyoから画像を取得する
get_image : Klaviyoから特定の画像を取得する

電子商取引

get_catalogs : Klaviyoからカタログを取得する
get_catalog_items : Klaviyo のカタログからアイテムを取得する
get_catalog_item : Klaviyo のカタログから特定のアイテムを取得する
get_coupons : Klaviyoからクーポンを入手
create_coupon_code : Klaviyoで新しいクーポンコードを作成する

追加ツール

get_tags : Klaviyoからタグを取得する
create_tag : Klaviyoで新しいタグを作成する
add_tag_to_resource : Klaviyo のリソースにタグを追加する
get_webhooks : KlaviyoからWebhookを取得する
create_webhook : Klaviyo で新しい Webhook を作成する
delete_webhook : Klaviyo から Webhook を削除します
request_profile_deletion : データプライバシーコンプライアンスのためのプロファイルの削除をリクエストする
get_forms : Klaviyoからフォームを取得する
get_form : Klaviyoから特定のフォームを取得する
get_product_reviews : Klaviyo から製品レビューを取得する
get_product_review : Klaviyo から特定の製品のレビューを取得する

🔗 利用可能なリソース

klaviyo://profile/{id} : 特定のプロフィールに関する情報を取得する
klaviyo://list/{id} : 特定のリストに関する情報を取得する
klaviyo://segment/{id} : 特定のセグメントに関する情報を取得する
klaviyo://campaign/{id} : 特定のキャンペーンに関する情報を取得する
klaviyo://flow/{id} : 特定のフローに関する情報を取得する
klaviyo://template/{id} : 特定のテンプレートの情報を取得する
klaviyo://metric/{id} : 特定のメトリックに関する情報を取得する
klaviyo://catalog/{id} : 特定のカタログに関する情報を取得する

⚠️ 既知の問題と制限事項

Klaviyo APIはレポートエンドポイントにレート制限を課す可能性があります
一部の指標はAPIで利用できるようになるまでに時間がかかる場合があります
履歴データの利用可能範囲は、Klaviyoプランによって制限される場合があります。
Claude Desktop を使用する場合、機能に影響しない JSON 解析の警告が表示されることがあります。

📝 ライセンス

このプロジェクトはオリジナルのKlaviyo MCPサーバーから派生したものです。ライセンス情報については、オリジナルの作者にお問い合わせください。

👥 貢献者

マット・コートワースによるオリジナル作品
イヴァン・リベラによる強化版