mailchimp-mcp-server

<div align="center">
  <h1>@cyanheads/mailchimp-mcp-server</h1>
  <p><b>Draft, test, and send Mailchimp campaigns straight from your MCP client — with audience management, subscriber CRUD, and post-send analytics behind safe-by-default send gates. STDIO or Streamable HTTP.</b>
  <div>18 Tools (+2 conditional) • 4 Resources • 1 Prompt</div>
  </p>
</div>

<div align="center">

[![Version](https://img.shields.io/badge/Version-0.3.12-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/mailchimp-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.2.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/mailchimp-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/mailchimp-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.2-blueviolet.svg?style=flat-square)](https://bun.sh/)

</div>

<div align="center">

[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/cyanheads/mailchimp-mcp-server/releases/latest/download/mailchimp-mcp-server.mcpb) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=mailchimp-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvbWFpbGNoaW1wLW1jcC1zZXJ2ZXIiXSwiZW52Ijp7Ik1BSUxDSElNUF9BUElfS0VZIjoieW91ci1hcGkta2V5In19) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22mailchimp-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Fmailchimp-mcp-server%22%5D%2C%22env%22%3A%7B%22MAILCHIMP_API_KEY%22%3A%22your-api-key%22%7D%7D)

[![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)

</div>

---

## Overview

Mailchimp campaign management over the Mailchimp Marketing API v3. Draft, test, and send email campaigns, manage audiences and subscribers, and review post-send analytics from any MCP client, with optional local image and template directories for authoring. Runs as a stdio process or a local Streamable HTTP server.

### Tools

| Tool | Description |
|:---|:---|
| `mailchimp_account` | Account profile, plan, data center, and the Chimp Chatter activity feed |
| `mailchimp_audiences` | Read, create, and update audiences (lists), with per-audience analytics and signup-form config |
| `mailchimp_audience_overview` | One-call audience digest: info, stats, growth history, top email clients, merge-field schema |
| `mailchimp_subscribers` | Subscriber reads, updates, archive, tags, notes, and engagement history |
| `mailchimp_upsert_subscriber` | Add or update one subscriber idempotently, with status, merge fields, tags, and a note |
| `mailchimp_find_subscriber` | Locate a subscriber by email in one audience or across the account |
| `mailchimp_import_subscribers` | Batch add or update up to 500 subscribers per call, `pending` by default |
| `mailchimp_segments` | Segment CRUD (saved, static, fuzzy), member listing, and batch add/remove |
| `mailchimp_merge_fields` | Read, create, and update custom subscriber attributes |
| `mailchimp_campaigns` | Campaign records, content, send checklist, and RSS/resend controls |
| `mailchimp_send_campaign` | Compose a campaign and leave it as a draft, test it, send it, or schedule it in one call |
| `mailchimp_replicate_campaign` | Duplicate a campaign with overrides, then draft, test, send, or schedule |
| `mailchimp_reports` | Campaign reports: the index, one report, or one of ten report dimensions |
| `mailchimp_campaign_report` | Post-send digest: headline metrics plus top links, locations, and unsubscribes |
| `mailchimp_templates` | Mailchimp-hosted templates; reads work on free plans, writes need a paid plan |
| `mailchimp_files` | File Manager uploads, listing, renames, and deletes on Mailchimp's CDN |
| `mailchimp_search` | Search members or campaigns across the account |
| `mailchimp_assets` *(conditional: `MAILCHIMP_ASSETS_DIR`)* | Inspect and pre-warm uploads for `@assets/<path>` references in campaign HTML |
| `mailchimp_local_templates` *(conditional: `MAILCHIMP_TEMPLATES_DIR`)* | Author and render local `.eta` templates, the template write path on free plans |
| `mailchimp_playbook` | Procedural playbooks merged with live account state; advice only |

### Resources

| Resource | Description |
|:---|:---|
| `mailchimp://account` | Account snapshot: profile, plan, data center, total subscribers |
| `mailchimp://audiences/{audienceId}` | Audience snapshot: name, contact, stats, double opt-in status |
| `mailchimp://campaigns/{campaignId}` | Campaign snapshot: status, settings, recipients |
| `mailchimp://campaigns/{campaignId}/report` | Post-send headline metrics for a campaign |

All resource data is also reachable through tools; audiences and campaigns are listed with each tool's `list` operation.

### Prompts

| Prompt | Description |
|:---|:---|
| `newsletter_from_source` | Compose an editorial newsletter from a URL or brief, then walk it through draft, test, and send |

Design reference: [`docs/email-design-playbook.md`](./docs/email-design-playbook.md).

## Capability reference

### `mailchimp_account` <sub>tool</sub>

- `operation: info` returns profile, plan, data center, total subscribers, and industry benchmarks; `operation: activity-feed` returns Chimp Chatter events, paged by `count` (max 100, default 20) and `offset`
- An empty activity feed carries a `note` naming the likely causes

---

### `mailchimp_audiences` <sub>tool</sub>

- Operations: `list`, `get`, `create`, `update`, the analytics reads `list-activity`, `list-growth`, `list-clients`, `list-abuse-reports`, `list-locations`, and `get-signup-forms` / `customize-signup-forms` (takes `signupFormConfig`); every operation except `list` and `create` needs `audienceId`
- `create` requires `name`, `contact` (`company`, `address1`, `city`, `state`, `zip`, `country`), `permissionReminder`, and `campaignDefaults` (`fromName`, `fromEmail`, `language`)

---

### `mailchimp_audience_overview` <sub>tool</sub>

- `audienceId` plus `growthMonths` (1–36, default 12); returns info, stats, contact, campaign defaults, growth history, top email clients, and the merge-field schema
- `notes[]` explains empty growth or email-client arrays, separating "no data yet" from zero engagement

---

### `mailchimp_subscribers` <sub>tool</sub>

- `audienceId` on every call and `email` on every operation except `list` (filterable by `status`); operations: `list`, `get`, `update`, `archive`, `list-tags`, `set-tags`, `list-notes` / `add-note` / `update-note` / `delete-note` (by `noteId`), and `list-activity` / `list-events` / `list-goals`
- `set-tags` is declarative: `tags` becomes the full active set and every other tag is removed unless named in `preserveTags`. Mailchimp stores static-segment membership as a tag, so an unguarded sync drops it. Returns `tagsAdded`, `tagsRemoved`, and `tagsActive`

---

### `mailchimp_upsert_subscriber` <sub>tool</sub>

- `audienceId`, `email`, and `status` required; optional `mergeFields`, `tags` + `preserveTags` (same declarative sync as `set-tags`), `note`, `vip`, `language`; `updateExistingStatus: false` applies `status` to new records only
- Returns `isNew`, the resulting `status`, `tagsAdded` / `tagsRemoved` / `tagsFinal`, `noteAttached`, and `webUrl`
- `status: "pending"` sends Mailchimp's double opt-in email; `"subscribed"` needs documented consent

---

### `mailchimp_find_subscriber` <sub>tool</sub>

- `email`, scoped to one `audienceId` or, when omitted, every audience on the account (echoed as `searchedAcross`)
- Returns `exactMatches` and `fuzzyMatches` with merge fields and stats; `includeTags` (default `true`) adds each match's tags at one extra call per match

---

### `mailchimp_import_subscribers` <sub>tool</sub>

- `audienceId` and 1–500 `subscribers` rows per call; `status` defaults to `pending` (double opt-in) and a per-row `status` overrides it; `updateExisting` defaults to `false`, so existing records are skipped
- Returns `totalCreated`, `totalUpdated`, `errorCount`, and per-row `succeeded` and `failed` entries, failures carrying Mailchimp's `errorCode`

---

### `mailchimp_segments` <sub>tool</sub>

- `audienceId` on every call and `segmentId` on every operation except `list` (filterable by `type`: `saved`, `static`, `fuzzy`) and `create`; `create` / `update` take `name`, `staticEmails`, or saved-segment `options`
- `batch-update-members` applies `membersToAdd` / `membersToRemove` to a static segment and returns `added`, `removed`, and per-email `errors`
- Free plans get static and basic saved segments; advanced conditions need Premium and fail as `mailchimp_forbidden`

---

### `mailchimp_merge_fields` <sub>tool</sub>

- `list`, `get`, `create`, `update`; `create` requires `name`, `tag` (10 characters max), and `type`; `get` / `update` take `mergeId`
- `options` carries type-specific config: `choices` for `dropdown` / `radio`, `date_format` for `date` / `birthday`, `phone_format` for `phone`

---

### `mailchimp_campaigns` <sub>tool</sub>

- Operations: `list` (filter by `status`, `listId`, `sinceSendTime` / `beforeSendTime`), `get`, `create` (`type` of `regular` / `plaintext` / `rss`, plus `recipients` and `settings`), `update`, `replicate`, `get-content`, `se