Klaviyo MCP

Klaviyo MCP

Klaviyo MCP 服务。24 个只读工具，覆盖多个账户中的营销活动、流程、细分、指标、报告和档案。

安装

Claude Code：

claude mcp add klaviyo -e KLAVIYO_KEY_MAIN=pk_your_key -- npx -y @scalably-io/klaviyo-mcp

Codex：

codex mcp add klaviyo --env KLAVIYO_KEY_MAIN=pk_your_key -- npx -y @scalably-io/klaviyo-mcp

Claude Desktop：从最新的 GitHub 版本下载 klaviyo-mcp.mcpb 并打开。Claude Desktop 的安装表单仅接受一个账户（KLAVIYO_KEY_MAIN）。

设置

1. 在 Klaviyo 的“设置”>“API 密钥”中创建一个私有 API 密钥。
2. 为每个账户设置一个 KLAVIYO_KEY_<name>=pk_xxx 环境变量，例如 KLAVIYO_KEY_MAIN 或 KLAVIYO_KEY_STOREONE。服务会在启动时自动发现所有 KLAVIYO_KEY_* 变量；list_accounts 会显示发现的变量。
3. 多个 Klaviyo 账户（代理机构、多品牌组合）只能通过 Claude Code 或 Codex 使用，因为只有这两者允许传递任意额外环境变量。根据账户数量添加任意多个 KLAVIYO_KEY_<name> 变量，然后使用匹配的 account 参数（即 KLAVIYO_KEY_ 后面的名称，转换为小写）调用工具。
4. 所有 24 个工具均为只读。

工具（24）

工具	功能
list_accounts	列出所有已配置的 Klaviyo 账户。首先使用此工具查看有哪些品牌可用。
list_campaigns	列出指定 Klaviyo 账户近期的电子邮件营销活动。返回活动 ID、名称、状态和发送日期。
campaign_report	获取 Klaviyo 账户的电子邮件营销活动效果指标。返回指定时间段内的打开次数、点击次数、收入、退信率和退订次数。
list_metrics	列出 Klaviyo 账户可用的指标。使用此工具查找收入报告所需的“Placed Order”指标 ID。
multi_account_summary	从所有已配置的 Klaviyo 账户提取营销活动效果摘要。返回统一的跨品牌报告。
flow_report	获取 Klaviyo 账户的电子邮件流程（自动化）效果。返回欢迎系列、弃购、购后等流程的指标。
campaign_ab_report	获取 Klaviyo 账户中电子邮件/SMS 营销活动各个变体（A/B 组）的指标。按变体拆分结果，便于比较各组。
flow_series_report	获取 Klaviyo 账户的流程（自动化）时间序列指标。按时间间隔分组。
segment_report	获取 Klaviyo 账户的细分效果指标：成员数量、添加数和移除数。
form_report	获取 Klaviyo 账户的注册表单效果：浏览次数、提交次数和提交率。
list_segments	列出 Klaviyo 账户中的所有细分，以及名称、成员数量和创建日期。
list_lists	列出 Klaviyo 账户中的所有电子邮件列表，以及名称、加入订阅流程和创建日期。
list_flows	列出 Klaviyo 账户中的所有流程（自动化），以及名称、状态、触发类型和最后更新时间。
get_campaign_detail	按 ID 获取单个营销活动的完整详情：名称、状态、send_time、主题、预览文本、渠道和消息 ID。
list_suppressed_profiles	按单个原因列出被禁止接收电子邮件营销的档案。Klaviyo 对 suppression.reason 只允许使用 equals（不允许使用 any），因此需针对每个原因分别调用，才能获取完整信息。
metric_aggregate	在自定义时间范围和间隔内汇总任意 Klaviyo 指标（例如打开次数、点击次数、收入）的数值。
get_template	按 ID 获取电子邮件模板，包括 HTML/文本内容。用于审核/预览。
list_recent_events	列出 Klaviyo 账户的近期事件，可按 metric_id（例如 Placed Order）筛选。最多返回最近 100 条。
account_info	获取 Klaviyo 账户元数据：组织名称、时区、货币、联系电子邮件和行业。
list_tags	列出 Klaviyo 账户中的所有标签（用于标记营销活动、流程、细分和列表）。
list_templates	列出 Klaviyo 账户中的电子邮件模板（名称、编辑器类型、日期）。使用 get_template 获取单个模板的 HTML。
get_profile	按电子邮件或档案 ID 查找客户档案：姓名、位置以及电子邮件营销许可/禁止状态。
get_flow_detail	按 ID 获取流程结构：状态、触发器及其操作/步骤（类型、消息渠道）。使用 list_flows 获取 ID。
custom_report	专家级备用工具：运行任意 Klaviyo 数值或序列报告，可全面控制 statistics、group_by、filter、interval 和 timeframe。

配置

变量	必需	用途
KLAVIYO_KEY_MAIN（或任意 KLAVIYO_KEY_<name>）	是	一个 Klaviyo 账户的私有 API 密钥。每个账户对应一个变量；KLAVIYO_KEY_ 后的名称将成为 account 参数。
KLAVIYO_API_BASE	否	覆盖 Klaviyo API 基础 URL（默认值为 https://a.klaviyo.com/api）
KLAVIYO_RETRY_BASE_MS	否	重试退避的基础延迟，单位为毫秒（默认值为 1000）

回复格式

每个工具均返回纯 JSON，包含 status（succeeded、partial、no_op）、operation、summary、target、result、proof、warnings、recovery。失败时会抛出纯错误字符串：<code>: <message> <hint>。

限制

Klaviyo 对报告端点（campaign_report、flow_report、campaign_ab_report、flow_series_report、segment_report、form_report，以及用于值/序列报告的 custom_report）实施速率限制：每个账户每分钟最多 2 次请求。报告数据仅从 2023-06-01 起提供；自定义范围若早于该日期，则会截断至此起始日期。单次报告请求不能跨越一个日历年，因此较长的自定义范围会自动拆分为连续的年度区间，并在区间之间加入间隔延迟。

验证

每个发行版都会在 CHANGELOG.md 中列出软件包版本、.mcpb 的 sha256，以及其所依据的生产提交。每次推送时，CI 都会运行测试，并对打包后的 tarball 执行全新安装。

隐私政策

此服务在你的设备上本地运行，使用你自己的凭据。它不会收集个人数据、不包含遥测、不持久化存储任何内容，并且只会与其封装的供应商 API 通信。包括 Scalably 在内的任何第三方都不会收到你的数据。联系邮箱：[email protected]。规范文本：https://scalably.io/connector-privacy.html

许可证

MIT。版权所有：Scalably。