Klaviyo MCP Server

Klaviyo MCP 服务

一款功能全面的模型上下文协议（MCP）服务，可完整访问 Klaviyo 的 API 功能。此服务提供 34 个以上的工具，涵盖用户资料、营销活动、流程、列表、细分群体、事件等，让 Claude 等 AI 助手能够与 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 设有以下速率限制：

• 突发：每秒 75 个请求
• 持续：每分钟 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. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 发起 Pull Request

📄 许可证

本项目采用 MIT License 授权，详情请参阅 LICENSE 文件。

🆘 支持

• 问题反馈：GitHub Issues
• Klaviyo API 文档：Klaviyo Developer Portal
• MCP 文档：Model Context Protocol

🏆 为什么选择这个 MCP 服务？

这是目前最全面的 Klaviyo MCP 集成，提供：

• ✅ 完整的 API 覆盖范围——涵盖 Klaviyo 的所有主要端点
• ✅ 可用于生产环境——具备完善的错误处理和安全保障
• ✅ 易于使用——所有工具都采用一致的接口
• ✅ 文档完善——提供清晰的示例和设置说明
• ✅ 积极维护——定期更新和改进

非常适合希望将 Klaviyo 功能集成到 AI 驱动的工作流、客户服务自动化、营销自动化和数据分析任务中的企业。

---

满怀 ❤️ 为 Klaviyo 和 MCP 社区打造