Klaviyo MCP 服务器增强版

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

🌟 主要特点

• 高级分析和报告：访问活动绩效指标、汇总数据和详细见解

• 全面的 API 覆盖：支持所有 Klaviyo API 端点的最新版本（2024-06-15）

• 性能优化：智能缓存、速率限制处理和高效数据处理

• 强大的错误处理：回退机制、详细日志记录和优雅降级

• 轻松集成：通过模型上下文协议与 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 Server的增强版本。原始作品为此增强版本提供了基础。

🚀 入门

先决条件

• Node.js v18 或更高版本

• 具有 API 访问权限的 Klaviyo 帐户

• 具有适当范围的私有 API 密钥（campaigns:read、metrics:read 等）

安装

1. 克隆此存储库：

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

2. 安装依赖项：

   npm install

3. 根据.env.example创建.env文件：

   cp .env.example .env

4. 编辑.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

启动服务器

以开发模式启动服务器并自动重新加载：

对于生产用途：

使用 MCP Inspector 进行测试

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

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

📚 文档

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

• ANALYTICS.md - 分析功能和使用的综合文档

• docs/KLAVIYO_API_REFERENCE.md - Klaviyo API 参数参考

🔍 使用示例

获取广告系列效果指标

查询聚合指标

获取广告系列效果摘要

🛠️ 可用工具

分析与报告（增强版新增功能）

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

⚠️ 已知问题和限制

• Klaviyo API 可能会对报告端点施加速率限制

• 某些指标在 API 中可用之前可能会有延迟

• 历史数据的可用性可能会根据您的 Klaviyo 计划而受到限制

• 与 Claude Desktop 一起使用时，您可能会偶尔看到不影响功能的 JSON 解析警告

📝 许可证

本项目源自原版 Klaviyo MCP 服务器。请联系原作者获取许可信息。

👥 贡献者

• 原创作品： Matt Coatsworth

• Ivan Rivera的增强版

🔗 外部资源

• Klaviyo API 文档

• 模型上下文协议

• 克劳德文档