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">

[![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) [![Version](https://img.shields.io/badge/Version-0.3.7-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-^1.29.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![TypeScript](https://img.shields.io/badge/TypeScript-^6.0.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.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/mailchimp-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>

---

## Tools

Eighteen always-on tools plus two conditional ones — `mailchimp_assets` (when `MAILCHIMP_ASSETS_DIR` is set) and `mailchimp_local_templates` (when `MAILCHIMP_TEMPLATES_DIR` is set). Workflow helpers orchestrate common flows end-to-end, primitive tools expose fine-grained CRUD, and the instruction tool returns procedural guidance merged with live account state.

| Tool Name | Description |
|:----------|:------------|
| `mailchimp_account` | Account profile, plan, data center, total subscribers, and the Chimp Chatter activity feed. |
| `mailchimp_audiences` | Manage audiences (lists) — read, create/update, per-audience analytics, signup-form config. No delete. |
| `mailchimp_audience_overview` | One-call audience health digest: info, stats, growth history, top email clients, merge-field schema. |
| `mailchimp_subscribers` | Subscriber CRUD + tags/notes/activity. `archive` is the strongest delete available. |
| `mailchimp_upsert_subscriber` | Add or update a subscriber idempotently with status, merge fields, tags, and optional note. |
| `mailchimp_find_subscriber` | Locate a subscriber by email in one audience or across the account. |
| `mailchimp_import_subscribers` | Batch add/update subscribers (capped at 500/call). Status defaults to `pending` (double-opt-in). |
| `mailchimp_segments` | CRUD for audience segments (saved, static, fuzzy) plus member listing and batch add/remove. |
| `mailchimp_merge_fields` | Read + create/update custom subscriber attributes. No delete — drops data across all subscribers. |
| `mailchimp_campaigns` | Campaign record management: list/get/create/update, replicate, content, checklist, RSS/resend controls. |
| `mailchimp_send_campaign` | Compose and send (or schedule/test) a campaign in one call. Elicits human confirmation on send/schedule. |
| `mailchimp_replicate_campaign` | Duplicate a campaign with optional overrides, then draft/test/send/schedule. Same elicit + cleanup semantics. |
| `mailchimp_reports` | Campaign reports — generic slicer across ten dimensions (clicks, opens, locations, etc.). |
| `mailchimp_campaign_report` | Post-send analytics digest — headline metrics + top 5 slices in one response. |
| `mailchimp_templates` | Email template read/write — reads (`list`/`get`) work on free for `base`/`user` types; writes (`create`/`update`/`delete`) and `gallery` require a paid plan. |
| `mailchimp_files` | File Manager (Content Studio) — upload, list, fetch, rename, delete files on Mailchimp's CDN. Embed the returned `fullSizeUrl` in campaign HTML. Works on free; 1 MB per image / 10 MB per other file. |
| `mailchimp_search` | Global search across members or campaigns. Lightweight discovery — use `find_subscriber` for detail. |
| `mailchimp_assets` *(conditional — set `MAILCHIMP_ASSETS_DIR`)* | Local-assets surface. List your assets dir, inspect cache state, pre-warm uploads ahead of a send. Most workflows don't call this directly — `@assets/<path>` references in campaign HTML auto-upload via `mailchimp_send_campaign` and `mailchimp_campaigns set-content`. |
| `mailchimp_local_templates` *(conditional — set `MAILCHIMP_TEMPLATES_DIR`)* | Local-template authoring surface. List/get/render-preview your `.eta` templates with optional `<name>.meta.yaml` sidecars. `seed-from-mailchimp` bootstraps a local template from a Mailchimp `base`/`user` starter. Use `content.localTemplate` on campaign tools to render at send time. **Canonical write path on free-tier Mailchimp**, where the upstream templates API is read-only. |
| `mailchimp_playbook` | Returns a structured procedural playbook merged with live account state. Advice-only, no writes. |

---

### `mailchimp_send_campaign`

Compose and send (or schedule/test) a campaign in one call.

- Chains create → content → checklist → optional test → send/schedule
- Requests human confirmation via `ctx.elicit` when `mode: 'send' | 'schedule'` and the client supports elicitation
- Auto-deletes aborted or failed drafts when `cleanupOnError: true` (default)
- Supports `html`, `plaintext`, and `templateId + mergeData` content forms

---

### `mailchimp_replicate_campaign`

Duplicate an existing campaign with optional overrides, then send/schedule/test or leave as draft.

- Overrides: subject, from name, reply-to, audience, segment, content
- Same elicit confirmation + cleanup semantics as `mailchimp_send_campaign`
- Tuned for the common "send v2 of last week's newsletter with an updated intro" pattern

---

### `mailchimp_upsert_subscriber`

Add or update a subscriber in one idempotent call.

- Declarative tag sync — pass the desired active set and the tool computes the add/remove delta
- `preserveTags` protects named segment memberships (Mailchimp stores static-segment membership as tags)
- `status: 'pending'` triggers Mailchimp's double-opt-in email; `'subscribed'` requires documented consent
- PUT `/members/{hash}` for create path, PATCH for update to skip re-validating pre-existing merge fields

---

### `mailchimp_import_subscribers`

Batch add (and optionally update) subscribers in one call.

- Capped at 500 rows per call — chunk larger imports client-side
- Status defaults to `pending` (double-opt-in) to prevent accidental mass-sends
- Returns per-row succeeded/failed with error reasons

---

### `mailchimp_campaign_report`

Aggregated post-send analytics for a campaign.

- Headline delivery metrics: sent, bounces, abuse reports
- Engagement: opens, clicks, unsubscribes
- Top-N clicked links, locations, recent unsubscribes
- Industry benchmarks when available
- Use `mailchimp_reports` with `operation: 'slice'` for a single dimension in detail

---

### `mailchimp_audience_overview`

Single-call audience health digest — answers "what does this audience look like?" in one request.

- Audience info + live stats
- Configurable months of growth history
- Top email clients
- Full merge-field schema
- Recent activity

---

### `mailchimp_playbook`

Returns a structured procedural playbook merged with live account state. Advice-only — the agent executes subsequent steps with other tools.

- Topics: `send`, `post-send-review`, `deliverability`, `list-hygiene`, `onboarding`, `subscriber-triage`, `design-campaign`
- Returns markdown instructions + a live-state snapshot
- `nextToolSuggestions` pre-fills arguments for the next likely tool call

## Resources and prompts

| Type | Name | Description |
|:---|:---|:---|
| Resource | `mailchimp://account` | Account info snapshot — profile, plan, data center, total subscribers. |
| Resource | `mailchimp://audiences/{audienceId}` | Audience snapshot — name, contact, stats, double-opt-in status. |
| Resource | `mailchimp://campaigns/{campaignId}` | Campaign snapshot — status, settings, recipients summary. |
| Resource | `mailchimp://campaigns/{campaignId}/report` | Post-send campaign report headline metrics. |
| Prompt | `newsletter_from_source` | User-invokable starter — compose a monthly editorial newsletter from a URL or brief. Chains into `mailchimp_playbook` (`topic: design-campaign`) and walks the draft → test → send flow. |

All resource data is also reachable via tools. Large collections (`audiences`, `campaigns`) are not exposed as resources — use the `list` operation on the corresponding tool instead. Design reference for the prompt: [`docs/email-design-playbook.md`](./docs/email-design-playbook.md).

## Features

Built on [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core):

- Declarative tool, resource, and prompt definitions — single file per primitive, framew