HelloWorld
登录
i

ivan-rivera-projects

customer-data-platformsmarketingrag-systems

323 查看 · 2026-07-07 更新

Klaviyo MCP Server Enhanced

smithery badge Klaviyo + MCP API Version Node.js

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

🌟 主要特性

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

📊 分析与报告能力

这个增强版本增加了原版中没有的强大分析能力：

  • 活动性能指标：打开率、点击率、弹跳率等
  • 自定义指标聚合：按时间段、维度和度量标准聚合指标
  • 收入归因：跟踪由活动和流程产生的收入
  • 订阅者洞察：分析订阅者的增长、参与度和行为

🔧 技术增强

1. 集中式配置 ✅

  • 创建了一个中央配置系统 (src/config.js) 用于所有API参数
  • 使API修订日期、有效统计信息和其他参数易于配置
  • 当API参数发生变化时，防止不同文件之间出现不一致

2. 增强的日志系统 ✅

  • 实现了具有不同日志级别（调试、信息、警告、错误）的强大日志系统
  • 添加了针对API请求和响应的专门日志记录
  • 在日志中屏蔽敏感数据以确保安全
  • 可配置的日志目的地和详细程度

3. 智能速率限制 ✅

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

4. 性能缓存 ✅

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

5. 错误处理与回退机制 ✅

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

🔄 API 版本

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

📋 致谢

这个项目是基于Matt Coatsworth创建的原始Klaviyo MCP服务器的增强版本。原始工作为这个增强版本奠定了基础。

🚀 开始使用

前提条件

  • Node.js v18或更高版本
  • 具有API访问权限的Klaviyo账户- 一个具有适当权限范围的私有 API 密钥（如 campaigns:read, metrics:read 等）

⚠️ 关于启动警告的重要说明

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

这些警告发生在 Claude 与 MCP 服务器初次连接期间，并不会影响工具的功能。一旦 Claude 完全初始化，这些警告将不再出现，工具将正常工作。

需要记住的关键点：

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

有关这些警告的更多技术细节，请参阅 STARTUP_ERROR_SUPPRESSION.md。

通过 Smithery 安装

要通过 Smithery 自动安装 Klaviyo 增强版分析服务器：

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

安装

  1. 克隆此仓库： bash git clone https://github.com/ivan-rivera-projects/Klaviyo-MCP-Server-Enhanced.git cd Klaviyo-MCP-Server-Enhanced

  2. 安装依赖项： bash npm install

  3. 根据 .env.example 创建一个 .env 文件： bash 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

启动服务器

以开发模式启动服务器并启用自动重载： bash npm run dev

用于生产环境： bash npm start

使用 MCP 检查器进行测试

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

bash npm run inspect

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

📚 文档

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

🔍 使用示例

获取活动性能指标

javascript // 获取活动的打开率和点击率 get_campaign_metrics({ id: "01JSQRND0PMH88186NREAJEGGN", metrics: ["open_rate", "click_rate", "delivered", "bounce_rate"], conversion_metric_id: "VevE7N", // 下单指标 ID start_date: "2025-04-01T00:00:00Z", // 可选：自定义日期范围 end_date: "2025-05-01T00:00:00Z" // 可选：自定义日期范围 })

查询聚合指标

javascript // 按月统计下单数量 query_metric_aggregates({ metric_id: "VevE7N", // 下单指标 ID measurement: "count", group_by: ["month"], timeframe: "last_30_days", // 预定义时间范围 // 或者使用自定义日期： start_date: "2025-01-01T00:00:00Z", end_date: "2025-05-01T00:00:00Z" })

获取活动性能摘要

javascript // 获取活动的全面性能摘要 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服务器。请联系原作者获取许可信息。

👥 贡献者

🔗 外部资源

来源