Mailchimp Mcp Server

Mailchimp MCP 服务

这是功能最全面的 Mailchimp Marketing API Model Context Protocol (MCP) 服务，提供 227 个工具，可通过任何兼容 MCP 的客户端查询和管理 Mailchimp 账户。它覆盖完整的营销活动、受众、成员、细分、自动化和报告功能，还支持完整的电子商务（读取和写入）、落地页、文件管理器、调查、注册表单和已验证域名，以及多账户支持和运行时安全防护（只读、试运行和审计模式，并为每个工具提供风险元数据）。

通过 requests 调用 Mailchimp Marketing API。不基于官方的 mailchimp-marketing-python 客户端。我在使用它时遇到了太多问题，所以改用了原始 HTTP 请求。

快速开始

uvx mailchimp-mcp   # no install required; just needs MAILCHIMP_API_KEY

将其添加到 MCP 客户端（Claude Desktop、Cursor、Cline 等）：

{
  "mcpServers": {
    "mailchimp": {
      "command": "uvx",
      "args": ["mailchimp-mcp"],
      "env": {
        "MAILCHIMP_API_KEY": "your-key-us8",
        "MAILCHIMP_READ_ONLY": "true"
      }
    }
  }
}

提示：先使用 MAILCHIMP_READ_ONLY=true 安全地进行探索，准备好写入时再将其关闭。所有选项请参阅配置。

Docker

每次发布新版本时，都会将预构建镜像发布到 GitHub Container Registry：

docker run --rm -i -e MAILCHIMP_API_KEY=your-key-us8 ghcr.io/damientilman/mailchimp-mcp-server:latest

也可以让 MCP 客户端连接到该镜像：

{
  "mcpServers": {
    "mailchimp": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "MAILCHIMP_API_KEY", "-e", "MAILCHIMP_READ_ONLY", "ghcr.io/damientilman/mailchimp-mcp-server:latest"],
      "env": {
        "MAILCHIMP_API_KEY": "your-key-us8",
        "MAILCHIMP_READ_ONLY": "true"
      }
    }
  }
}

功能

读取

• 营销活动 - 列出、搜索和查看营销活动详情
• 报告 - 打开率/点击率、退信、每个链接的点击量、域名表现、退订详情
• 邮件活动 - 跟踪每位收件人的打开/点击情况、成员活动历史记录
• 受众 - 浏览受众、成员、细分、标签和增长历史记录
• 合并字段 - 列出受众的自定义字段
• 兴趣类别与分组 - 浏览兴趣类别和选项
• Webhook - 列出已配置的 Webhook
• 细分 - 获取细分详情、条件和成员列表
• 自动化 - 列出工作流、查看工作流中的邮件、查看队列
• 模板 - 浏览模板并提取 HTML 内容
• 落地页 - 列出和查看落地页
• 文件管理器 - 浏览存储的图片、文件和文件夹
• 调查 - 列出和查看受众的调查
• 注册表单 - 查看受众的注册表单
• 电子商务 - 商店、订单、产品、客户（需要电子商务集成）
• 营销活动文件夹 - 浏览文件夹组织结构
• 批量操作 - 监控批量操作状态

写入

• 成员 - 添加、更新、退订和删除联系人，以及为联系人添加标签
• 受众 - 批量订阅成员、更新受众设置
• 营销活动 - 创建草稿、设置 HTML 内容、安排发送、取消安排、复制、删除、发送、发送测试邮件、取消
• 细分/标签 - 创建、更新、删除、添加/移除成员、设置动态条件
• 合并字段 - 创建、更新和删除自定义字段
• 兴趣类别 - 创建和删除类别及兴趣
• Webhook - 创建和删除 Webhook
• 模板 - 创建、更新和删除邮件模板
• 文件管理器 - 上传（base64）和删除图片及文件
• 调查 - 发布和取消发布受众调查
• 注册表单 - 自定义标题、内容和样式
• 自动化 - 暂停和启动自动化工作流
• 电子商务 - 用于折扣工作流的购物车生命周期、促销规则和促销代码
• 批量 - 在单个请求中运行批量 API 操作

运行时安全

• 风险元数据 - 通过 MCP 注释和 describe_tools 对每个工具进行读取/写入/破坏性操作分类
• 审计日志 - 可选的结构化 JSON 审计事件，每次分派时生成（MAILCHIMP_AUDIT_LOG）
• 参数验证 - 在每次请求前检查分页上限和必需 ID

前提条件

• Python 3.10+
• Mailchimp API 密钥

安装

使用 uvx（推荐）

无需安装 — 直接运行：

uvx mailchimp-mcp

使用 pip

pip install mailchimp-mcp

然后运行：

mailchimp-mcp

从源代码安装

git clone https://github.com/damientilman/mailchimp-mcp-server.git
cd mailchimp-mcp-server
python -m venv .venv
source .venv/bin/activate
pip install -e .

配置

系统会自动从每个密钥中提取数据中心（us8、us21 等）。

安全模式

只读模式 — 当 MAILCHIMP_READ_ONLY=true 时，所有写入工具（创建、更新、删除、安排等）都会被阻止并返回错误。读取工具照常工作。对于共享或探索性配置，如果只需要报告和分析，建议默认启用此模式。

试运行模式 — 当 MAILCHIMP_DRY_RUN=true 时，写入工具会返回其将要执行操作的预览（工具名称、目标资源、参数及其风险等级），而不会发出任何 API 调用。可用于在正式启用前测试提示词。

运行时安全

此服务旨在与外部 MCP 网关配合，构建纵深防御：它负责定义语义（哪些工具属于读取、可撤销写入或不可撤销操作），并将其作为机器可读信号公开，供网关强制执行，而不是让网关猜测哪些调用具有危险性。

风险元数据 — 每个工具都被归类为 read、write 或 destructive（不可逆的数据丢失或不可撤销的发送操作）。这些信息通过两种方式呈现：

• MCP 工具注释 — readOnlyHint、destructiveHint 和 idempotentHint 会通过标准的 tools/list 传递，因此任何兼容的客户端或网关都可以直接读取。
• describe_tools — 一个读取工具，会为每个工具返回 {name, risk, read_only, destructive, idempotent} 及各风险等级的计数，供倾向于通过工具调用获取信息的网关使用。

结构化审计日志 — 启用 MAILCHIMP_AUDIT_LOG=true 后，每次调度都会向 stderr 输出一个 JSON 事件，其中包含工具、风险等级、destructive 标志、目标账户、结果（executed / blocked_read_only / dry_run）以及经过检查的参数。体积较大或敏感的值（例如 base64 file_data）会被脱敏，且绝不记录响应正文，因此该数据流可安全地集中转存并持续监控。

参数契约验证 — 所有写入操作都会经过统一的 _guard_write 检查点，并且每个请求都会在调度前完成验证（分页 count 限制为 1–1000，缺失的路径 ID 会被拒绝），因此格式错误的调用会快速且一致地失败，而不会触达 API。

工具配置

每次交互都向模型发送全部 227 个工具会产生很长的工具列表（约 63k 个 token）。如果只需要部分工具，可以用一行加载子集：

"env": { "MAILCHIMP_API_KEY": "your-key-us8", "MAILCHIMP_TOOLS": "read" }

MAILCHIMP_TOOLS 接受以逗号分隔的风险等级（read、write、destructive）和／或确切的工具名称；符合任一条件的工具都会被保留。未设置（或设为 all）时，会公开所有工具。

• read — 仅用于报告和分析（约 115 个工具、约 29k 个 token）。适合探索的安全轻量默认配置。
• read,write — 除不可逆工具外的所有工具。
• list_campaigns,get_campaign_report,send_campaign — 精选的最小工具集。

工具描述在发送给模型前也会删去重复的模板内容，因此即使使用完整工具集，内容也比原始文档字符串更精简。使用 describe_tools 查看每个工具的风险等级。

多账户

默认情况下，服务使用单个 MAILCHIMP_API_KEY，并将其作为 default 账户公开。若要通过一台服务管理多个 Mailchimp 账户，请添加 MAILCHIMP_API_KEY_<NAME> 变量 — 后缀会成为小写账户名称（例如，MAILCHIMP_API_KEY_MARKETING → marketing）。

此后，每个工具都会接受可选的 account 参数，例如 list_audiences(account="marketing")。选择按调用进行，且不保存状态 — 没有可供切换的“当前账户”，因此写入操作始终会明确指定目标账户。省略 account 时会使用 default。调用 list_accounts 可查看已配置的名称及其安全标志状态；每个账户还可以拥有自己的 MAILCHIMP_READ_ONLY_<NAME> / MAILCHIMP_DRY_RUN_<NAME> 标志（因此，受写入保护的账户可以与可写账户并存）。若指定了未知的 account，则会返回列出已配置名称的错误。

单密钥配置不受影响：只设置 MAILCHIMP_API_KEY 时，一切照旧。

{
  "mcpServers": {
    "mailchimp": {
      "command": "uvx",
      "args": ["mailchimp-mcp"],
      "env": {
        "MAILCHIMP_API_KEY": "your-default-key-us8",
        "MAILCHIMP_API_KEY_MARKETING": "another-key-us5",
        "MAILCHIMP_READ_ONLY_MARKETING": "true"
      }
    }
  }
}

MCP 客户端配置

大多数 MCP 客户端都接受用于描述如何启动服务的 JSON 配置块。 将客户端配置为调用 uvx mailchimp-mcp（或通过 pip 安装时调用 mailchimp-mcp）， 并在环境中导出 MAILCHIMP_API_KEY。

{
  "mcpServers": {
    "mailchimp": {
      "command": "uvx",
      "args": ["mailchimp-mcp"],
      "env": {
        "MAILCHIMP_API_KEY": "your-api-key-here"
      }
    }
  }
}

{
  "mcpServers": {
    "mailchimp": {
      "command": "mailchimp-mcp",
      "env": {
        "MAILCHIMP_API_KEY": "your-api-key-here"
      }
    }
  }
}

{
  "mcpServers": {
    "mailchimp": {
      "command": "uvx",
      "args": ["mailchimp-mcp"],
      "env": {
        "MAILCHIMP_API_KEY": "your-api-key-here",
        "MAILCHIMP_READ_ONLY": "true"
      }
    }
  }
}

基于 CLI 的客户端

如果你的 MCP 客户端提供用于注册服务的 CLI，则等效调用方式为：

mcp-cli add mailchimp \
  -e MAILCHIMP_API_KEY=your-api-key-here \
  -- uvx mailchimp-mcp

将 mcp-cli 替换为你的客户端二进制文件名。若要使用只读模式，请在命令中添加 -e MAILCHIMP_READ_ONLY=true。

可用工具

账户

营销活动（读取）

营销活动报告

营销活动（写入）

受众（读取）

成员（读取）

成员（写入）

受众（写入）

细分与标签

合并字段

兴趣类别与分组

Webhook

自动化与客户旅程

Mailchimp 不提供客户旅程的公开读取 API（仅提供上方的触发端点）。search_automation_campaigns、get_member_journey_events 和 get_automation_summary 工具提供了推荐的替代方案——它们会显示自动化或旅程发起的所有营销活动，即使旅程图本身仍不可见。

模板

落地页

文件管理器

调查问卷

注册表单

电子商务

电子商务购物车

电子商务促销规则和代码

批量操作

已验证域名

已连接的网站与账户

文件夹

营销活动附加功能（检查清单、协作、RSS）

受众洞察与送达能力

成员（合规与高级功能）

自动化电子邮件（单封邮件控制）

报告（其他）

电子商务（写入）

示例提示词

连接后，你可以让 MCP 客户端执行如下请求：

• “显示我过去 3 个月发送的所有营销活动”
• “我上一期电子简报的打开率和点击率是多少？”
• “我今年新增了多少订阅者？”
• “营销活动 X 中哪些链接获得了最多点击？”
• “搜索订阅者 [email protected]”
• “给打开了我上一期营销活动的所有成员添加标签 ‘VIP’”
• “为我的主要受众创建一封主题为 ‘March Update’ 的营销活动草稿”
• “创建一个仅面向我的 VIP 细分群体的营销活动”
• “将营销活动草稿的测试邮件发送到 [email protected]”
• “列出我的主要受众的所有合并字段”
• “创建一个名为 ‘Industry’ 的下拉合并字段，选项为 Tech、Finance、Healthcare”
• “创建一个 FNAME 为 John 的成员动态细分群体”
• “根据这份 CSV 数据批量订阅 50 位成员”
• “设置一个 webhook，在有新订阅者加入时通知我的应用”
• “将 [email protected] 从我的列表中取消订阅”
• “显示我上一期营销活动的域名表现明细”
• “大家在世界各地的哪些地方打开了我的电子简报？显示地理分布。”
• “创建一个包含两个主题行的 A/B 测试营销活动，并在 24 小时后根据打开次数选出获胜者”
• “Mailchimp 对改进我上一期营销活动有什么建议？”
• “暂停我的欢迎自动化流程”
• “列出我 Shopify 商店本月的所有订单”

工作流示例

端到端串联工具的多步骤请求：

• 每周效果回顾 — “总结我上周的情况：列出自周一以来发送的营销活动，获取每份报告，并按点击率排序，每项附上一条总结。” 串联 search_campaigns → get_campaign_report → get_campaign_advice。
• 送达率审查 — “检查我的发送状况：我的域名是否已验证？近期营销活动有任何垃圾邮件投诉吗？最近一次营销活动按收件人域名统计的表现如何？” 串联 list_verified_domains → get_campaign_abuse_reports → get_domain_performance。
• 重新互动 — “找出所有没有打开我最近一期简报的人，并用新的主题行重新发送。” 串联 get_campaign_report → resend_to_non_openers。
• 安全发送 — “对我的 VIP 客户群试运行营销活动，显示发送检查清单，然后等我确认后再发送。” 设置 MAILCHIMP_DRY_RUN=true 后，通过 create_campaign → get_campaign_send_checklist → send_campaign 进行预览。
• 代理机构（多账户） — “针对 acme 和 globex 两个账户，分别列出本月打开率最高的营销活动。” 每次调用时传入 account="acme" / account="globex"。参见多账户。

贡献

欢迎贡献。开发环境设置、测试说明和拉取请求指南，请参见 CONTRIBUTING.md。

安全

如果发现安全漏洞，请遵循 SECURITY.md 中说明的负责任披露流程。

更新日志

完整的发布历史请参见 CHANGELOG.md。

作者

由 Damien Tilman 构建 — [email protected]

许可证

MIT — 详情请参见 LICENSE。