mailchimp-mcp-server

---

概览

Mailchimp 营销活动管理。起草、测试和发送电子邮件营销活动，管理受众和订阅者，并查看发送后分析；还可选配本地图片和模板目录用于内容创作。

工具

工具	描述
mailchimp_account	账户资料、套餐、数据中心和 Chimp Chatter 活动动态
mailchimp_audiences	读取、创建和更新受众（列表），并提供按受众划分的分析数据和注册表单配置
mailchimp_audience_overview	一次调用获取受众摘要：信息、统计数据、增长历史、热门电子邮件客户端和合并字段架构
mailchimp_subscribers	订阅者的读取、更新、归档、标签、备注和互动历史
mailchimp_upsert_subscriber	以幂等方式添加或更新单个订阅者，并设置状态、合并字段、标签和备注
mailchimp_find_subscriber	在单个受众中或整个账户中按电子邮件查找订阅者
mailchimp_import_subscribers	每次调用批量添加或更新最多 500 位订阅者，默认状态为 pending
mailchimp_segments	细分受众群的增删改查（已保存、静态、模糊），成员列表，以及批量添加/移除
mailchimp_merge_fields	读取、创建和更新订阅者自定义属性
mailchimp_campaigns	营销活动记录、内容、发送检查清单以及 RSS/重发控制
mailchimp_send_campaign	一次调用即可撰写营销活动并将其保存为草稿、测试、发送或安排发送
mailchimp_replicate_campaign	复制营销活动并设置覆盖项，然后保存为草稿、测试、发送或安排发送
mailchimp_reports	营销活动报告：报告索引、单份报告或 10 种报告维度之一
mailchimp_campaign_report	发送后摘要：关键指标以及热门链接、位置和退订数据
mailchimp_templates	Mailchimp 托管的模板；免费套餐可读取，写入需要付费套餐
mailchimp_files	在 Mailchimp 的 CDN 上上传、列出、重命名和删除文件管理器中的文件
mailchimp_search	在整个账户中搜索成员或营销活动
mailchimp_assets (条件启用：MAILCHIMP_ASSETS_DIR)	检查并预热营销活动 HTML 中 @assets/<path> 引用对应的上传文件
mailchimp_local_templates (条件启用：MAILCHIMP_TEMPLATES_DIR)	编写并渲染本地 .eta 模板；这是免费套餐的模板写入路径
mailchimp_playbook	与实时账户状态合并的流程手册；仅提供建议

资源

资源	描述
mailchimp://account	账户快照：资料、套餐、数据中心、订阅者总数
mailchimp://audiences/{audienceId}	受众快照：名称、联系人、统计数据、双重选择加入状态
mailchimp://campaigns/{campaignId}	营销活动快照：状态、设置、收件人
mailchimp://campaigns/{campaignId}/report	营销活动发送后的关键指标

所有资源数据也可通过工具获取；受众和营销活动可通过各工具的 list 操作列出。

提示词

提示词	描述
newsletter_from_source	根据 URL 或简介撰写编辑类新闻简报，然后依次完成草稿、测试和发送流程

设计参考：docs/email-design-playbook.md。

能力参考

mailchimp_account _工具

• operation: info 返回资料、套餐、数据中心、订阅者总数和行业基准；operation: activity-feed 返回 Chimp Chatter 事件，可通过 count（最多 100，默认 20）和 offset 分页
• 活动动态为空时，会附带一条 note，说明可能的原因

---

mailchimp_audiences _工具

• 操作：list、get、create、update、分析数据读取操作 list-activity、list-growth、list-clients、list-abuse-reports、list-locations，以及 get-signup-forms / customize-signup-forms（接收 signupFormConfig）；除 list 和 create 外，所有操作都需要 audienceId
• create 需要 name、contact（company、address1、city、state、zip、country）、permissionReminder 和 campaignDefaults（fromName、fromEmail、language）

---

mailchimp_audience_overview _工具

• audienceId 和 growthMonths（1–36，默认值为 12）；返回信息、统计数据、联系人、营销活动默认值、增长历史、热门电子邮件客户端以及合并字段架构
• notes[] 说明增长或电子邮件客户端数组为空的原因，区分“暂无数据”和零互动

---

mailchimp_subscribers _工具

• 每次调用都需要 audienceId；除 list（可按 status 筛选）外，每项操作都需要 email；操作包括：list、get、update、archive、list-tags、set-tags、list-notes / add-note / update-note / delete-note（按 noteId 操作），以及 list-activity / list-events / list-goals
• 地址会先去除首尾空格；如果缺少本地部分或域名部分，则会被拒绝；list 的 email 为空时不会应用筛选。将状态 update 为 subscribed 时，如果是在恢复订阅，会要求确认；已订阅的成员则保持原状
• set-tags 是声明式操作：tags 会成为完整的活动标签集合，除非在 preserveTags 中指定，否则会移除其他所有标签（静态细分的成员资格会作为标签存储）。返回 tagsAdded、tagsRemoved 和 tagsActive

---

mailchimp_upsert_subscriber _工具

• 必须提供 audienceId、email 和 status；可选参数包括 mergeFields、tags + preserveTags（与 set-tags 使用相同的声明式同步方式）、note、vip、language；updateExistingStatus: false 只会将 status 应用于新记录
• 返回 isNew、最终的 status、tagsAdded / tagsRemoved / tagsFinal、noteAttached 和 webUrl
• status: "pending" 使用 Mailchimp 的双重选择加入流程。对于新的或恢复订阅的 subscribed 状态，在写入任何内容之前，都需要确认已记录的同意；如果拒绝，则不会写入任何内容。对于已订阅记录的更新以及 updateExistingStatus: false，会保留现有状态，无需确认

---

mailchimp_find_subscriber _工具

• email 接受电子邮件地址或自由格式的搜索片段，包括不含 @ 的片段；可限定在一个 audienceId 内搜索，或在省略该参数时搜索账户中的所有受众（通过 searchedAcross 返回搜索范围）
• 返回包含合并字段和统计数据的 exactMatches 和 fuzzyMatches；includeTags（默认值为 true）会为每个匹配项额外调用一次，以附加其标签

---

mailchimp_import_subscribers _工具

• 每次调用需要提供 audienceId 和 1–500 行 subscribers；status 默认为 pending（双重选择加入），每行的 status 可覆盖该默认值；updateExisting 默认为 false，因此会跳过现有记录
• 任何将设置为 subscribed 的行都需要在整个批次写入前进行一次确认；如果拒绝，则不会写入任何内容。仅导入待处理状态的记录无需确认
• 返回 totalCreated、totalUpdated、errorCount 以及逐行的 succeeded 和 failed 条目；地址不完整的记录会以 invalid_email 失败；批次中没有有效行时，不会发出上游请求

---

mailchimp_segments _工具

• 每次调用都需要 audienceId；除 list（可按 type 筛选：saved、static、fuzzy）和 create 外，每项操作都需要 segmentId；create / update 接受 name、staticEmails 或已保存细分的 options
• batch-update-members 会将 membersToAdd / membersToRemove 应用于静态细分，并返回 added、removed 和逐个电子邮件地址的 errors
• 免费套餐支持静态细分和基本的已保存细分；高级条件需要 Premium，否则会以 mailchimp_forbidden 失败

---

mailchimp_merge_fields _工具

• 支持 list、get、create、update；create 需要 name、tag（最多 10 个字符）和 type；get / update 需要 mergeId
• options 用于传递特定类型的配置：dropdown / radio 使用 choices，date / birthday 使用 date_format，phone 使用 phone_format

mailchimp_campaigns _工具

• 操作：list（按 status、listId、sinceSendTime / beforeSendTime 筛选）、get、create（type 为 regular / plaintext / rss，另需 recipients 和 settings）、update、replicate、get-content、set-content、get-checklist、cancel-send、create-resend、pause-rss、resume-rss；除 list 和 create 外，其他操作均需提供 campaignId
• set-content 接受 html、plainText、templateId + templateSections、archiveContent、url 或 localTemplate（不能与 html 和 templateId 同时使用）；get-checklist 返回 isReady 和带类型的条目
• get-content 接受 variant: html | plainText | archiveHtml | all（默认值为 all）；空正文会被省略
• 此处不支持发送、测试、排期或删除；发送操作通过 mailchimp_send_campaign 或 mailchimp_replicate_campaign 进行

---

mailchimp_send_campaign _工具

• 必须提供 audienceId、subject、fromName、replyTo 和 content（至少提供 html、plainText、templateId、localTemplate 中的一项）；mode 可以是 draft（默认值）、test（需要 testEmails，最多 50 个）、send 或 schedule（需要提供至少 15 分钟后的 scheduleTime）
• 返回 campaignId、实际生效的 mode、status、recipientCount、webUrl 和非阻塞的 checklistWarnings；在 draft 以外的模式下，阻塞性检查清单错误会抛出 pre_send_checklist_failed；发生中途流程失败时，cleanupOnError（默认值为 true）会删除草稿
• send 和 schedule 需要设置 confirmSend: true，之后会在创建任何 campaign 之前显示一次性确认提示；拒绝后会保留草稿并设置 cancelledByUser。内容变更或重放时会再次询问；上游失败状态不明确时，绝不会重试创建操作

---

mailchimp_replicate_campaign _工具

• 提供 sourceCampaignId，以及可选的 subjectOverride、previewTextOverride、fromNameOverride、replyToOverride、titleOverride、audienceOverride、segmentOverride 和 contentOverride；mode、testEmails、scheduleTime 和 cleanupOnError 的用法与 mailchimp_send_campaign 相同
• 返回新的 campaignId、overridesApplied[]，以及相同的状态、检查清单和 cancelledByUser 字段
• send 和 schedule 同样需要设置 confirmSend: true 并通过确认提示门槛

---

mailchimp_reports _工具

• list（按 type、sinceSendTime / beforeSendTime 筛选）、get，或使用 campaignId 和 dimension 执行 slice；dimension 可为：abuse-reports、advice、click-details（通过 linkId 指定一个 URL）、open-details（通过 subscriberHash 指定一个成员）、domain-performance、eepurl、email-activity、locations、sent-to、unsubscribed
• slice 返回按维度定义结构的 rows 以及 totalItems；对于尚未发送的 campaign，get 会抛出 campaign_not_sent

---

mailchimp_campaign_report _工具

• 提供 campaignId 和 includeTopN（每个切片返回 1–100 行，默认值为 10）
• 返回 delivery（送达数、按类型划分的退信数、滥用举报）、engagement（打开数、点击数、取消订阅数）、topClickedLinks、topLocations、recentUnsubscribes；如果 Mailchimp 提供了行业基准数据，也会返回 industryBenchmarks；对于尚未发送的 campaign，会抛出 campaign_not_sent

---

mailchimp_templates _工具

• list（按 type 为 user / base / gallery、category、folderId 筛选）、get、get-default-content、create、update 和 delete；update 仅接受 name、html 和 folderId，因此各分区的编辑需通过 campaign 的 templateSections 进行
• 免费套餐支持读取 base 和 user 模板；写入和读取 gallery 需要付费套餐，否则会失败并返回 mailchimp_forbidden。所有套餐均可通过 mailchimp_local_templates 创建模板

---

mailchimp_files _工具

• list（可按 type、folderId、sinceCreatedAt / beforeCreatedAt 筛选）、get、upload（name 需包含扩展名，fileData 为 base64，不带 data: 前缀）、update（重命名，或使用 folderId 移动，0 表示根目录）、delete，以及只读的 list-folders / get-folder；图片上传上限为每张 1 MB，其他文件为 10 MB；不接受 .webp / .avif
• upload 和 get 会返回 fullSizeUrl，即用于嵌入营销活动 HTML 的公共 CDN URL；list 会额外返回 totalFileSizeInBytes

---

mailchimp_search _工具

• scope（members 或 campaigns）和 query；audienceId 可缩小成员搜索范围；includeTopN（1–100，默认值为 10）用于限制每个结果数组的条目数
• 成员搜索结果以 exact 和 fuzzy 返回，并包含上游的 totalExact / totalFuzzy；营销活动搜索结果以 matches 返回，并包含 snippet 和 totalMatches；结果为空时会附带 note

---

mailchimp_assets _工具

• list、info（按 relPath 查询；返回 sha256 和任何已缓存的上传文件）、sync（发送前上传尚未缓存的文件；返回 uploaded、cached，以及带原因说明的 skipped）和 clear-cache
• 传递给 mailchimp_send_campaign、mailchimp_replicate_campaign 或 mailchimp_campaigns set-content 的内容中，@assets/<path> 引用会被上传到 File Manager，并替换为 CDN URL。上传文件按 SHA-256 缓存至 <assetsDir>/.mailchimp-cache.json；超出大小限制的文件及目录外的路径会在上传前被拒绝
• 仅在设置了 MAILCHIMP_ASSETS_DIR 时列出

---

mailchimp_local_templates _工具

• list、get（源文件及解析后的元数据）、render-preview（name 和 vars；返回 HTML，不会发送任何内容）和 seed-from-mailchimp（将 Mailchimp 模板 mailchimpTemplateId 写入磁盘，文件名为 name）
• 模板为 .eta 文件，可选用 YAML frontmatter 声明 subject、previewText 和 vars；已声明但未提供的变量会导致渲染失败。营销活动工具可通过 content.localTemplate + content.localTemplateVars 渲染模板，且不能与 html 和 templateId 同时使用。示例模板
• 仅在设置了 MAILCHIMP_TEMPLATES_DIR 时列出

---

mailchimp_playbook _工具

• topic：send、post-send-review、deliverability、list-hygiene、onboarding、subscriber-triage 或 design-campaign；send / list-hygiene / design-campaign 需要 audienceId，post-send-review 需要 campaignId，subscriber-triage 需要 email
• 返回根据实时数据定制的 Markdown instructions、liveState 快照，以及带预填输入的 nextToolSuggestions；不会执行写入操作

---

mailchimp://account _资源

• 无参数；返回包含个人资料、套餐、数据中心、订阅者总数和 fetchedAt 的 application/json
• 数据与 mailchimp_account 的 operation: info 相同

---

mailchimp://audiences/{audienceId} _资源

• 名称、联系信息、统计数据、营销活动默认设置、许可提醒、双重选择加入状态和订阅 URL
• audienceId 来自 mailchimp_audiences 的 operation: list

---

mailchimp://campaigns/{campaignId} _资源

• 状态、设置、收件人、跟踪信息和报告摘要
• campaignId 来自 mailchimp_campaigns 的 operation: list

---

mailchimp://campaigns/{campaignId}/report _资源

• 已发送邮件数、退信数、打开数、点击数、退订数、滥用举报数和行业统计数据
• 营销活动发送前调用会因验证错误而失败

---

newsletter_from_source _提示词

• 参数：必填的 source（URL 或自由格式的简报）；可选的 audienceId 和 seasonalContext
• 返回一条用户消息，其中先调用 mailchimp_playbook（topic: design-campaign），再生成 HTML 草稿，随后通过 mailchimp_send_campaign 创建草稿、测试并发送

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可切换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），并提供结构化日志记录和可选的 OpenTelemetry 跟踪。

Mailchimp 专属功能：

• Marketing API v3 客户端可根据 API 密钥的 -<dc> 后缀推导 API 主机和数据中心，并支持重试、进程级并发限制（MAILCHIMP_CONCURRENCY_LIMIT）以及 429 响应后的冷却时间
• 发送关卡：Campaign 默认处于 draft 状态；send / schedule 需要设置 confirmSend: true 并提供确认提示词；新建或恢复为 subscribed 状态的订阅也需要确认；导入默认处于 pending 状态
• 不执行不可逆删除：移除受众、合并字段或 Campaign，以及永久删除订阅者，需在 Mailchimp 界面中操作；archive 是移除订阅者的最彻底方式
• 本地创作：@assets/<path> 文件会在发送时上传并重写；.eta 模板在本地渲染，适用于 Templates API 只读的免费套餐
• 列表操作支持通过 count（最大值为 1000）和 offset 分页

便于 Agent 使用的输出：

• 说明空结果：当活动动态、受众概览和搜索结果为空时，note / notes[] 会说明是缺少数据还是真正的零结果
• 部分失败：mailchimp_import_subscribers 和 mailchimp_segments 的 batch-update-members 会逐行返回成功结果和错误，而不会导致整个批次失败
• 判别式输出：operation、dimension 和 mode 指明哪些字段已填充；isNew 和 cancelledByUser 报告实际发生的情况
• 类型化错误：每个已声明的原因（campaign_not_sent、pre_send_checklist_failed、mailchimp_forbidden，等等）都会附带恢复提示，告知调用方下一步该怎么做

开始使用

将以下内容添加到 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

配置

变量	说明	默认值
MAILCHIMP_API_KEY	必填。 Marketing API 密钥，包含 -dc 后缀（例如 abc…-us22）。	无
MAILCHIMP_BASE_URL	API 基础 URL 覆盖项，用于模拟服务或测试。	https://{dc}.api.mailchimp.com/3.0
MAILCHIMP_TIMEOUT_MS	每个请求的超时时间，单位为毫秒。	60000
MAILCHIMP_MAX_RETRIES	上游临时故障时的重试次数（0–10）。	3
MAILCHIMP_CONCURRENCY_LIMIT	整个进程中同时进行的上游请求数上限（1–10）。	4
MAILCHIMP_ASSETS_DIR	本地资源目录的绝对路径。启用 mailchimp_assets 以及在营销活动 HTML 中使用 @assets/<path> 上传资源。	无
MAILCHIMP_TEMPLATES_DIR	本地模板目录的绝对路径。启用 mailchimp_local_templates 和营销活动工具中的 content.localTemplate。	无
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_SESSION_MODE	会话模式；确认操作需要 stateful，而 stateless 会拒绝启动 HTTP（不影响 stdio）。	stateful
MCP_REQUEST_STATE_KEY	可选的密封密钥，至少 32 字节。确认操作只能使用一次且与单个进程绑定，因此重启或使用其他实例时会再次询问。	无
MCP_AUTH_MODE	身份验证方式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（debug、info、warning、error 等）。	info
LOGS_DIR	日志文件目录（仅限 Node.js）。	<app-root>/logs
OTEL_ENABLED	启用 OpenTelemetry。	false
OTEL_EXPORTER_OTLP_ENDPOINT	追踪和指标的基础 URL。	无
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	OTLP 日志端点；除非设置此项，否则不会导出日志。	无
LOG_TOOL_FAILURE_PAYLOADS	记录失败调用的参数和结果，按键名脱敏，并限制在 LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES（默认值为 16384）以内。自由格式值中的机密仍会显示。	false

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

运行服务

本地开发

• 监视模式（传输方式由 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 可省略这些依赖。

项目结构

目录	用途
src/index.ts	createApp() 入口：注册工具、资源和提示词，并初始化服务。
src/config	使用 Zod 解析并验证 MAILCHIMP_* 环境变量。
src/mcp-server/tools	工具定义（*.tool.ts）以及用于模板渲染、资源重写和发送确认的共享辅助函数。
src/mcp-server/resources	资源定义（*.resource.ts）。
src/mcp-server/prompts	提示词定义（*.prompt.ts）。
src/services/mailchimp	Mailchimp API 客户端：HTTP、请求节流、重试、响应规范化。
src/services/assets	本地资源：发现、哈希、上传缓存、@assets/ 重写。
src/services/templates	本地模板：Eta 渲染、frontmatter 解析、从 Mailchimp 填充模板。
templates/	.eta 模板示例；将 MAILCHIMP_TEMPLATES_DIR 指向此目录即可试用。
docs/	API 密钥指南和电子邮件设计手册。
tests/	用于配置、服务、工具和提示词的 Vitest 测试套件。

开发指南

开发指南和架构规则请参阅 CLAUDE.md。简而言之：

• 由处理程序抛出异常，框架负责捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录请求范围内的日志
• 通过 src/mcp-server/*/definitions/index.ts 中的汇总文件注册新工具和资源
• 封装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出架构；切勿伪造缺失字段

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

Apache-2.0 — 详情请参阅 LICENSE。