Klaviyo MCP Server

Klaviyo MCP サーバー

Klaviyo API のすべての機能に完全にアクセスできる、包括的な Model Context Protocol（MCP）サーバーです。このサーバーにより、Claude などの AI アシスタントは、プロフィール、キャンペーン、フロー、リスト、セグメント、イベントなどをカバーする 34 個以上のツールを通じて、Klaviyo の主要な API をすべて利用できます。

🚀 特長

API を幅広く網羅

• Profiles API（4 個のツール） - 顧客プロフィールの作成、読み取り、更新、検索
• Lists API（4 個のツール） - リストとリストのメンバーシップを管理
• Campaigns API（4 個のツール） - メールキャンペーンの作成、管理、送信
• Segments API（3 個のツール） - 動的な顧客セグメントの作成と検索
• Events API（3 個のツール） - 顧客イベントの追跡と取得
• Flows API（3 個のツール） - 自動メールフローの管理
• Metrics API（2 個のツール） - パフォーマンス指標へのアクセス
• Templates API（2 個のツール） - メールテンプレートの管理
• Catalogs API（3 個のツール） - 商品カタログとバリエーションの管理
• Coupons API（2 個のツール） - 割引クーポンの作成と管理
• Reporting API（2 個のツール） - キャンペーンとフローの分析データの検索
• Accounts API（2 個のツール） - アカウント情報へのアクセス

主な特長

• ✅ 34 個のツールで Klaviyo API の主要なエンドポイントをすべてカバー
• ✅ Klaviyo のプライベート API キーを使用した安全な認証
• ✅ ネットワーク、HTTP、API エラーに対応する包括的なエラー処理
• ✅ タイムアウトと再試行のロジックによるレート制限への対策
• ✅ すべてのパラメーターと JSON データに対する入力検証
• ✅ 一貫したインターフェース - すべてのツールが同じパターンに従います
• ✅ フィルタリング、ページネーション、ソートに対応したJSON:API 形式
• ✅ 使用例を含む完全なドキュメント

📋 前提条件

• Python 3.10 以降
• API にアクセスできる Klaviyo アカウント
• Klaviyo プライベート API キー（こちらから取得）

🛠️ インストール

クイックセットアップ

1. リポジトリをクローンする：

   git clone https://github.com/relay-commerce/Klaviyo-MCP-Server.git
   cd Klaviyo-MCP-Server
   

2. セットアップスクリプトを実行する：

   chmod +x klaviyo_setup.sh
   ./klaviyo_setup.sh
   

3. Klaviyo API キーを取得する：

   • Klaviyo API Keys に移動します
   • 適切なスコープを設定して、新しいプライベート API キーを作成します

手動セットアップ

1. 仮想環境を作成する：

   python3 -m venv klaviyo_mcp_env
   source klaviyo_mcp_env/bin/activate
   

2. 依存関係をインストールする：

   pip install -r klaviyo_requirements.txt
   

🧪 テスト

サーバーが正常に動作していることを確認するため、テストを実行します。

source klaviyo_mcp_env/bin/activate
python test_klaviyo_server.py

利用可能なツールが 34 個すべてであることを示す出力が表示されます。

✅ SUCCESS: All expected tools are available!
Test completed. Total tools available: 34

🔧 使用方法

Claude Desktop で使用する

Claude Desktop の設定ファイルにサーバーを追加します。

macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "klaviyo": {
      "command": "python",
      "args": ["/absolute/path/to/klaviyo_mcp_server.py"]
    }
  }
}

MCP CLI で使用する

# List available tools
mcp-cli tool list --server klaviyo

# Call a specific tool
mcp-cli tool call get_profiles --server klaviyo --input '{"api_key": "your-api-key"}'

📖 API の使用例

顧客プロフィールを作成する

create_profile(
    api_key="your-api-key",
    profile_data='{"email": "[email protected]", "first_name": "John", "last_name": "Doe"}'
)

すべてのキャンペーンを取得する

get_campaigns(
    api_key="your-api-key",
    filter_expr="equals(status,'draft')",
    page_size=50
)

カスタムイベントを追跡する

create_event(
    api_key="your-api-key",
    event_data='{"metric": {"name": "Placed Order"}, "profile": {"email": "[email protected]"}, "properties": {"value": 99.99, "item_count": 2}}'
)

顧客セグメントを作成する

create_segment(
    api_key="your-api-key",
    segment_data='{"name": "High Value Customers", "definition": {"condition_groups": [{"conditions": [{"field": "properties.total_spent", "operator": "greater-than", "value": 1000}]}]}}'
)

キャンペーンを送信する

send_campaign(
    api_key="your-api-key",
    campaign_id="campaign-id-here"
)

🔐 認証

このサーバーは、認証に Klaviyo プライベート API キーを使用します。各ツールで api_key パラメーターが必要です。

• API キーをコードにハードコードしないでください
• 各ツール呼び出しのパラメーターとして API キーを渡してください
• 実行する操作に必要なスコープが API キーに設定されていることを確認してください

必要な API スコープ

Klaviyo API キーに次のスコープが設定されていることを確認してください。

• profiles:read、profiles:write
• lists:read、lists:write
• campaigns:read、campaigns:write
• segments:read、segments:write
• events:read、events:write
• flows:read、flows:write
• metrics:read
• templates:read、templates:write
• catalogs:read、catalogs:write
• coupons:read、coupons:write

📊 利用可能なツール

Profiles API（4 個のツール）

• get_profiles() - フィルタリング、ページネーション、並べ替えを使用してすべてのプロフィールを一覧表示
• create_profile() - 新しい顧客プロフィールを作成
• get_profile() - ID で特定のプロフィールを取得
• update_profile() - 既存のプロフィールデータを更新

Lists API（4 個のツール）

• get_lists() - アカウント内のすべてのリストを一覧表示
• create_list() - 新しいリストを作成
• get_list_profiles() - 特定のリスト内のプロフィールを取得
• add_profiles_to_list() - リストにプロフィールを追加

Campaigns API（4 個のツール）

• get_campaigns() - すべてのキャンペーンを一覧表示
• create_campaign() - 新しいメールキャンペーンを作成
• get_campaign() - 特定のキャンペーンの詳細を取得
• send_campaign() - キャンペーンをすぐに送信

Segments API（3 個のツール）

• get_segments() - すべてのセグメントを一覧表示
• create_segment() - 新しい動的セグメントを作成
• get_segment_profiles() - セグメント内のプロフィールを取得

Events API（3 個のツール）

• get_events() - フィルタリングと並べ替えを使用してイベントを一覧表示
• create_event() - 新しい顧客イベントを記録
• get_event() - 特定のイベントの詳細を取得

Flows API（3 個のツール）

• get_flows() - すべての自動フローを一覧表示
• get_flow() - 特定のフローの詳細を取得
• update_flow_status() - フローのステータスを更新（draft/live/stopped/archived）

その他の API

Metrics API（2 個のツール）

• get_metrics() - 利用可能なすべてのメトリクスを一覧表示
• get_metric() - 特定のメトリクスの詳細を取得

Templates API（2 個のツール）

• get_templates() - すべてのメールテンプレートを一覧表示
• create_template() - 新しいメールテンプレートを作成

Catalogs API（3 個のツール）

• get_catalog_items() - カタログアイテムを一覧表示
• create_catalog_item() - 新しいカタログアイテムを作成
• get_catalog_variants() - カタログバリエーションを一覧表示

Coupons API（2 個のツール）

• get_coupons() - すべてのクーポンを一覧表示
• create_coupon() - 新しいクーポンを作成

Reporting API（2 個のツール）

• query_campaign_values() - キャンペーンのパフォーマンス指標を取得
• query_flow_values() - フローのパフォーマンス指標を取得

Accounts API（2 個のツール）

• get_accounts() - アカウント情報を取得
• get_account() - 特定のアカウントの詳細を取得

⚡ レート制限

Klaviyo には次のレート制限があります。

• バースト：1 秒あたり 75 リクエスト
• 通常：1 分あたり 700 リクエスト

このサーバーには、タイムアウト処理とレート制限発生時の適切なエラーメッセージを備えた保護機能が組み込まれています。

🛡️ セキュリティ

• ✅ API キーはパラメーターとして渡されます（ハードコードされません）
• ✅ すべてのリクエストで HTTPS を使用します
• ✅ 適切なエラー処理により、機密データの漏えいを防ぎます
• ✅ すべてのパラメーターを入力検証します
• ✅ コードやログにシークレットを保存しません

🔧 技術的な詳細

• API ベース URL：https://a.klaviyo.com/api
• API リビジョン：2025-04-15
• プロトコル：JSON:API 形式
• 認証：Klaviyo-API-Key ヘッダー
• Python バージョン：3.10+
• MCP バージョン：1.0.0+

📁 ファイル構成

Klaviyo-MCP-Server/
├── klaviyo_mcp_server.py      # Main MCP server implementation
├── klaviyo_requirements.txt   # Python dependencies
├── klaviyo_setup.sh          # Setup script
├── klaviyo_documentation.md  # Detailed documentation
├── test_klaviyo_server.py    # Test script
└── README.md                 # This file

🤝 貢献

1. リポジトリをフォークします
2. フィーチャーブランチを作成します（git checkout -b feature/amazing-feature）
3. 変更をコミットします（git commit -m 'Add amazing feature'）
4. ブランチにプッシュします（git push origin feature/amazing-feature）
5. プルリクエストを作成します

📄 ライセンス

このプロジェクトは MIT ライセンスの下で公開されています。詳細は LICENSE ファイルをご覧ください。

🆘 サポート

• 問題：GitHub Issues
• Klaviyo API ドキュメント：Klaviyo Developer Portal
• MCP ドキュメント：Model Context Protocol

🏆 この MCP サーバーが選ばれる理由

これは利用可能な中で最も包括的な Klaviyo MCP インテグレーションであり、以下を提供します。

• ✅ API を網羅 - Klaviyo の主要なエンドポイントすべてに対応
• ✅ 本番環境に対応 - 適切なエラー処理とセキュリティ
• ✅ 使いやすい - すべてのツールで一貫したインターフェース
• ✅ 充実したドキュメント - わかりやすい使用例とセットアップ手順
• ✅ 積極的にメンテナンス - 定期的な更新と改善

Klaviyo の機能を AI を活用したワークフロー、カスタマーサービスの自動化、マーケティングの自動化、データ分析のタスクに統合したい企業に最適です。

---

Klaviyo と MCP のコミュニティのために、❤️を込めて作成