# ivan-rivera-projects
## 基本信息
- Slug: `ivan-rivera-projects-klaviyo-mcp-server-enhanced`
- Source: modelscope
- Publisher: @ivan-rivera-projects/Klaviyo-MCP-Server-Enhanced
- Categories: customer-data-platforms / marketing / rag-systems
- Hosted: No
- License: Unknown
- Source URL: https://www.modelscope.cn/mcp/servers/@ivan-rivera-projects/Klaviyo-MCP-Server-Enhanced
## 简介
暂无描述。
## MCP Server 详情

# Klaviyo MCP Server Enhanced

[![smithery badge](https://smithery.ai/badge/@ivan-rivera-projects/Klaviyo-MCP-Server-Enhanced)](https://smithery.ai/server/@ivan-rivera-projects/Klaviyo-MCP-Server-Enhanced)
![Klaviyo + MCP](https://img.shields.io/badge/Klaviyo-MCP-blue)
![API Version](https://img.shields.io/badge/API%20Version-2024--06--15-green)
![Node.js](https://img.shields.io/badge/Node.js-v18%2B-brightgreen)

一个全面的模型上下文协议（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](https://github.com/mattcoatsworth)创建的[原始Klaviyo MCP服务器](https://github.com/mattcoatsworth/Klaviyo-MCP-Server)的增强版本。原始工作为这个增强版本奠定了基础。

## 🚀 开始使用

### 前提条件

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

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

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

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

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

有关这些警告的更多技术细节，请参阅 [STARTUP_ERROR_SUPPRESSION.md](docs/STARTUP_ERROR_SUPPRESSION.md)。

### 通过 Smithery 安装

要通过 [Smithery](https://smithery.ai/server/@ivan-rivera-projects/Klaviyo-MCP-Server-Enhanced) 自动安装 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 参数的详细信息，请参阅：

- [ANALYTICS.md](ANALYTICS.md) - 分析特性和用法的综合文档
- [docs/KLAVIYO_API_REFERENCE.md](docs/KLAVIYO_API_REFERENCE.md) - Klaviyo 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}`: 获取关于特定模板的信息
- `kla…