Klaviyo MCP Server Enhanced

Klaviyo MCP服务器增强

用于与Klaviyo API交互的综合模型上下文协议（MCP）服务器。此增强版本提供了高级分析功能、性能优化和强大的错误处理，同时保持了与原始MCP服务器的完全兼容性。

🌟 主要特点

• 高级分析和报告：访问活动绩效指标、汇总数据和详细见解
• API全面覆盖：支持最新版本的所有Klaviyo API端点（2024-06-15）
• 性能优化：智能缓存、速率限制处理和高效的数据处理
• 稳健的错误处理：回退机制、详细的日志记录和优雅的降级
• 易于集成：通过模型上下文协议与Claude和其他LLM无缝集成

📊 分析和报告能力

此增强版本添加了原始版本中没有的强大分析功能：

• 活动绩效指标：打开率、点击率、跳出率等
• 自定义度量聚合：按时间段、维度和度量值汇总指标
• 收入归属：跟踪活动和流量产生的收入
• 订阅者洞察：分析用户增长、参与度和行为

🔧 技术增强

1.集中配置✅

• 创建了一个中央配置系统(src/config.js)对于所有API参数
• 使API修订日期、有效统计数据和其他参数易于配置
• 防止了API参数更改时不同文件之间的不一致

2.增强型测井系统✅

• 实现了一个具有不同日志级别（调试、信息、警告、错误）的强大日志系统
• 为API请求和响应添加了专门的日志记录
• 为了安全起见，在日志中隐藏敏感数据
• 可配置的日志目标和详细程度

3.智能速率限制✅

• 为速率限制错误添加了重试逻辑
• 实现了具有抖动的指数回退重试
• 遇到费率限制时添加了明确的反馈
• 在速率限制期间优先处理关键请求

4.性能缓存✅

• 为频繁访问的数据实现内存缓存
• 添加了基于TTL（生存时间）的缓存失效
• 针对不同数据类型（指标、活动等）优化缓存
• 用于监控和优化的缓存统计信息

5.错误处理和回退✅

• 针对所有API交互的全面错误处理
• 主请求失败时降级操作的回退机制
• 详细的错误消息和故障排除信息
• 高级JSON解析错误预防和处理
• 智能缓冲区管理，用于从损坏的消息中恢复
• 自动清除格式错误的JSON输入
• 抑制错误弹出窗口，以获得更好的用户体验

🔄 API版本

此增强版本使用Klaviyo API修订版 2024-06-15，其中包括最新功能和改进。服务器设计为通过集中式配置系统与未来API修订版向前兼容。

📋 归因

🚀 入门指南

先决条件

• Node.js v18或更高版本
• 具有API访问权限的Klaviyo帐户
• 具有适当作用域（活动：读取、指标：读取等）的专用API密钥

⚠️ 关于启动警告的重要提示

当您首次使用此MCP工具启动Claude Desktop时，您将看到几个JSON解析错误通知。这是正常和预期的行为。

这些警告发生在Claude和MCP服务器之间的初始连接阶段，不会影响工具的功能。一旦Claude完全初始化，这些警告将停止出现，工具将正常工作。

要记住的要点：

• 这些警告是无害的，可以安全地忽略
• 它们仅在启动时出现，在正常运行时不出现
• 尽管有这些警告，MCP服务器仍正常运行
• 所有分析和API功能将按预期工作

有关这些警告的更多技术详细信息，请参阅 STARTUP_RENGSUPPRESSION.md.

通过Smithery安装

通过以下方式自动安装Klaviyo增强型分析服务器for Claude Desktop 史密瑟里:

npx -y @smithery/cli install @ivan-rivera-projects/Klaviyo-MCP-Server-Enhanced --client claude

安装

1. 克隆此存储库：

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

1. 安装依赖项：

   npm install

1. 创建一个 .env 文件基于 .env.example:

   cp .env.example .env

1. 编辑 .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检验员测试

您可以使用MCP检查器测试服务器：

npm run inspect

这将打开一个web界面，您可以在其中测试所有可用的工具和资源。

📚 文档

有关分析功能和API参数的详细信息，请参阅：

• 分析.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：更新克拉维约的流量状态

内容管理

• 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获取webhooks
• 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}：获取特定目录的信息

⚠️ 已知问题和限制

• API可能会对报告终点实施利率限制
• 某些度量在API中可用之前可能会有延迟
• 根据您的Klaviyo计划，历史数据可用性可能会受到限制
• 启动Claude Desktop时，您将看到JSON解析警告。这些是预期的，不会影响功能（请参阅上文“关于启动警告的重要说明”部分）

📝 许可证

该项目源自原始的Klaviyo MCP服务器。请联系原作者以获取许可信息。

👥 贡献者

• 原创作品由 马特·科茨沃斯
• 增强版由 伊万·里维拉

🔗 外部资源

• Klaviyo API文档
• 模型上下文协议
• 克劳德文件