STARWARCLOUD STARWAR.AI
返回市场
Klaviyo-MCP-服务器-增强版

Klaviyo-MCP-服务器-增强版

作者：ivan-rivera-projects3 星标更新：2025-05-17
安装使用来源：spider==github.com

项目介绍

Klaviyo MCP Server 增强版

smithery 徽章 Klaviyo + MCP API 版本 Node.js

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

🌟 主要特性

  • 高级分析与报告：访问活动表现指标、聚合数据及详细见解
  • 全面的 API 支持：支持所有 Klaviyo API 端点，包括最新修订版本（224-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 修订版本向前兼容。

📋 归属

此项目是 原版 Klaviyo MCP 服务器 的增强版，由 Matt Coatsworth 创作。原作品为这个增强版提供了基础。

🚀 开始使用

前提条件

  • 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 增强分析服务器到 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

  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

启动服务器

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

npm run dev

对于生产使用：

npm start

使用 MCP Inspector 测试

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

npm run inspect

这将打开一个 Web 接口，在那里你可以测试所有可用的工具和资源。

📚 文档

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

🔍 使用示例

获取活动表现指标

// 获取活动的打开率和点击率
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"    // 可选：自定义日期范围
})

查询聚合指标

// 按月分组计算下单数量
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"
})

获取活动表现概要

// 获取活动的综合表现概要
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 获取网络钩子
  • create_webhook：在 Klaviyo 中创建新的网络钩子
  • delete_webhook：删除 Klaviyo 中的网络钩子
  • 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 服务器。请联系原作者获取许可信息。

👥 贡献者

🔗 外部资源