@cyanheads/mailchimp-mcp-server

工具

十八个常驻工具，外加两个条件性工具——mailchimp_assets（当设置了 MAILCHIMP_ASSETS_DIR 时）和 mailchimp_local_templates（当设置了 MAILCHIMP_TEMPLATES_DIR 时）。工作流辅助工具端到端编排常见流程，基础工具提供细粒度的 CRUD 操作，指令工具则返回结合实时账户状态的操作指导。

mailchimp_send_campaign

在一次调用中编写并发送（或安排/测试）营销活动。

• 串联执行：创建 → 内容 → 检查清单 → 可选测试 → 发送/安排

• 当 mode: 'send' | 'schedule' 时，在任何营销活动变更之前，通过可重入的输入轮次请求人工确认。

• 当 cleanupOnError: true（默认）时自动删除失败的草稿；拒绝确认则保留可审阅的草稿。

• 支持 html、plaintext、templateId + templateSections 以及本地 Eta 模板内容形式。

mailchimp_replicate_campaign

复制现有营销活动并可选覆盖设置，然后发送/安排/测试或保留为草稿。

• 覆盖项：主题、发件人名称、回复地址、受众、分段、内容。

• 与 mailchimp_send_campaign 相同的可重入确认 + 清理语义。

• 针对常见的“发送上周新闻通讯的 v2 版本并更新引言”模式进行了优化。

mailchimp_upsert_subscriber

在一次幂等调用中添加或更新订阅者。

• 声明式标签同步 — 传入所需的活动集合，工具会计算添加/移除的差异。

• preserveTags 保护命名分段成员资格（Mailchimp 将静态分段成员资格存储为标签）。

• status: 'pending' 会触发 Mailchimp 的双重选择加入邮件；'subscribed' 需要记录在案的同意。

• 创建路径使用 PUT /members/{hash}，更新使用 PATCH，以跳过对已有合并字段的重新验证。

mailchimp_import_subscribers

在一次调用中批量添加（并可选择更新）订阅者。

• 每次调用上限 500 行 — 较大的导入请在客户端分块处理。

• 状态默认为 pending（双重选择加入），以防止意外群发。

• 返回每行的成功/失败状态及错误原因。

mailchimp_campaign_report

营销活动的聚合发送后分析。

• 核心投递指标：发送、退信、滥用举报

• 互动情况：打开、点击、退订

• 点击量最高的 N 个链接、地理位置、最近的退订

• 行业基准（如有）

• 如需详细了解单个维度，请使用 mailchimp_reports 并设置 operation: 'slice'

mailchimp_audience_overview

单次调用即可获取受众健康度摘要——一次请求回答“这个受众是什么样的？”。

• 受众信息 + 实时统计

• 可配置的成长历史月份数

• 主流电子邮件客户端

• 完整的合并字段架构

• 近期活动

mailchimp_playbook

返回一份与实时账户状态合并的结构化程序化操作手册。仅提供建议——代理使用其他工具执行后续步骤。

• 主题：send、post-send-review、deliverability、list-hygiene、onboarding、subscriber-triage、design-campaign

• 返回 Markdown 指令 + 实时状态快照

• nextToolSuggestions 为下一个可能的工具调用预填参数

Related MCP server: Mailchimp MCP Server

资源和提示

所有资源数据也可以通过工具访问。大型集合（audiences、campaigns）不会作为资源暴露——请改用相应工具的 list 操作。该提示的设计参考：docs/email-design-playbook.md。

功能特性

基于 @cyanheads/mcp-ts-core 构建：

• 声明式工具、资源和提示定义——每个原语一个文件，框架负责注册和验证

• 统一的错误处理——处理程序抛出异常，框架负责捕获、分类和格式化

• 可插拔的身份验证：none、jwt、oauth

• 结构化日志，可选 OpenTelemetry 追踪

• STDIO 和 Streamable HTTP 传输

Mailchimp 专属特性：

• 从 API 密钥的 -dc 后缀自动推导 API 基础 URL

• 默认安全的发送工作流——可重入确认、待处理状态导入、代理操作面不提供永久删除

• 工作流工具在可配置的并发限制下并行处理相关的子请求

• 域规范化将稀疏的上游负载整理为紧凑、对 LLM 友好的输出，且不会虚构值

快速开始

将以下内容添加到你的 MCP 客户端配置文件中。有关如何生成 Mailchimp API 密钥，请参阅 docs/api-key.md。

{
  "mcpServers": {
    "mailchimp-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/mailchimp-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "MAILCHIMP_API_KEY": "your-key-with-dc-suffix-e.g.-us22"
      }
    }
  }
}

或者使用 npx（无需 Bun）：

{
  "mcpServers": {
    "mailchimp-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/mailchimp-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "MAILCHIMP_API_KEY": "your-key-with-dc-suffix-e.g.-us22"
      }
    }
  }
}

或者使用 Docker：

{
  "mcpServers": {
    "mailchimp-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "MAILCHIMP_API_KEY=your-key-with-dc-suffix-e.g.-us22",
        "ghcr.io/cyanheads/mailchimp-mcp-server:latest"
      ]
    }
  }
}

对于 Streamable HTTP，设置传输方式并启动服务器：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 MAILCHIMP_API_KEY=... bun run start:http
# Server listens at http://localhost:3010/mcp

前提条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。

• 一个 Mailchimp Marketing API 密钥——密钥的 -dc 后缀（例如 -us22）标识你的数据中心，并在启动时解析。

安装

1. 克隆仓库：

git clone https://github.com/cyanheads/mailchimp-mcp-server.git

2. 进入目录：

cd mailchimp-mcp-server

3. 安装依赖：

bun install

4. 配置环境：

cp .env.example .env
# edit .env and set MAILCHIMP_API_KEY

配置

完整的可选覆盖项列表请参阅 .env.example。

本地资源（可选）

设置 MAILCHIMP_ASSETS_DIR 以在 Mailchimp 的 File Manager 之上启用本地图片工作流。将图片文件放入该目录，在 HTML 中以 @assets/<relative-path> 引用，服务器会在发送时上传并重写。

export MAILCHIMP_ASSETS_DIR=/Users/me/Pictures/email-assets

然后在营销活动中：

<img src="@assets/hero.png" alt="Hero">
<a href="@assets/whitepaper.pdf">Download</a>

当 mailchimp_send_campaign（或 mailchimp_campaigns set-content / mailchimp_replicate_campaign contentOverride）看到这些引用时，它会：

1. 对每个被引用的文件进行哈希处理（SHA-256）。

2. 通过 mailchimp_files 工具接口将缓存未命中的文件上传到 Mailchimp File Manager。

3. 将 sha256 → file_id + URL 缓存到 <assetsDir>/.mailchimp-cache.json（原子写入；可安全删除以强制重新上传）。

4. 在将内容传递给上游之前，将每个 @assets/<path> 重写为公共 CDN URL。

mailchimp_assets 工具提供 list、info、sync（预热）和 clear-cache 操作，便于直接检查——大多数工作流不需要它。

注意事项：

• Mailchimp 将图片大小限制为 1 MB，其他文件限制为 10 MB。超限文件会在上传前失败，并给出可操作的错误信息。

• 允许的扩展名：请参阅 mailchimp_files 工具描述。WebP 和 AVIF 不在允许列表中——请转换为 PNG/JPG。

• 路径遍历会被拒绝（../ 和绝对路径会抛出 Forbidden）。

• mailchimp_assets 工具仅限 Node.js；在 Cloudflare Workers 上不会注册该工具。

本地模板（可选）

设置 MAILCHIMP_TEMPLATES_DIR 以在 Eta（v4——快速、原生 ESM、支持局部模板/条件/循环）之上启用本地模板编写工作流。这是免费版 Mailchimp 账户上模板的标准写入路径，因为上游 /templates API 是只读的。

export MAILCHIMP_TEMPLATES_DIR=/Users/me/email-templates

email-templates/
  welcome.eta              # body + optional YAML frontmatter
  newsletter.eta
  partials/
    header.eta
    footer.eta

模板（welcome.eta）——顶部为 YAML 前置元数据，下方为 Eta 主体：

---
subject: "Welcome to {{brand}}"
previewText: "Onboarding starts here"
vars:
  - firstName
  - brand
---
<%~ include('partials/header', it) %>
<h1>Hello <%= it.firstName %></h1>
<p>Welcome to <%= it.brand %>.</p>
<img src="@assets/hero.png" alt="Hero">

Frontmatter 是可选的——没有 --- 块的正文会被视为无元数据的模板。所有元数据字段也都是可选的。vars: 列表仅作参考（声明的变量不受 schema 强制约束）。

Sidecar 回退（旧版）： 在 v0.3.1 之前，元数据存放在正文旁边的独立 <name>.meta.yaml 文件中。这种形式仍然有效以保持向后兼容——如果 .eta 没有 frontmatter，加载器会回退到读取 sidecar。当两者都存在时，frontmatter 优先。

从任意 campaign 工具中引用：

{
  "audienceId": "abc123",
  "subject": "Welcome to Acme",
  "fromName": "Casey",
  "replyTo": "casey@acme.com",
  "content": {
    "localTemplate": "welcome",
    "localTemplateVars": { "firstName": "Sam", "brand": "Acme" }
  },
  "mode": "draft"
}

渲染流水线：

1. Eta 使用 it = { firstName: 'Sam', brand: 'Acme' } 渲染 welcome.eta。

2. 如果配置了 L1，@assets/hero.png 会被上传到 Mailchimp File Manager 并重写为 CDN URL。

3. 最终 HTML 通过 Mailchimp 的 set-content 设置到 campaign 上。

mailchimp_local_templates 工具提供 list、get、render-preview（返回 HTML 但不发送）和 seed-from-mailchimp（按 ID 读取 Mailchimp 的 base/user 模板并将其写入磁盘作为起点——在免费版上很有用，因为那里只能读取而不能写入上游）。

本仓库中的示例模板

templates/ 目录包含可运行的示例——将 MAILCHIMP_TEMPLATES_DIR 直接指向该目录即可试用，或将其复制到您自己的目录中作为起点：

注意事项：

• 在同一内容块上，localTemplate 与 html 和 templateId 互斥。

• schema 不强制进行 var 校验——缺失/多余的 var 会在发送时以 Eta 渲染错误的形式暴露出来。

• 拒绝路径遍历。

• 仅限 Node；在 Workers 上不可用。

运行服务器

本地开发

• 监听模式（通过 MCP_TRANSPORT_TYPE 传输）：

  bun run dev                                     # stdio (default)
  MCP_TRANSPORT_TYPE=http bun run dev             # http

• 构建并运行：

  bun run rebuild
  bun run start:stdio
  # or
  bun run start:http

• 运行检查和测试：

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec

Docker

docker build -t mailchimp-mcp-server .
docker run --rm -e MAILCHIMP_API_KEY=your-key-us22 -p 3010:3010 mailchimp-mcp-server

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/mailchimp-mcp-server。默认会安装 OpenTelemetry 对等依赖——使用 --build-arg OTEL_ENABLED=false 构建可将其省略。

项目结构

开发指南

开发指南和架构规则请参阅 CLAUDE.md。简要版本：

• 处理器抛出异常，框架捕获——工具逻辑中不使用 try/catch

• 使用 ctx.log 进行请求作用域的日志记录

• 通过 src/mcp-server/*/definitions/index.ts 中的 barrel 文件注册新工具和资源

• 封装外部 API 调用：校验原始数据 → 规范化为领域类型 → 返回输出 schema；绝不虚构缺失字段

贡献

欢迎提交 issue 和 pull request。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

本项目采用 Apache 2.0 许可证。详情请参阅 LICENSE 文件。