.codex-plugin— 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">

</div>

<div align="center">

</div>

Overview

Mailchimp campaign management. Draft, test, and send email campaigns, manage audiences and subscribers, and review post-send analytics, with optional local image and template directories for authoring.

Tools

Resources

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

Prompts

Design reference: docs/email-design-playbook.md.

Capability reference

mailchimp_account _tool

• 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 _tool

• 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 _tool

• 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 _tool

• 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
• Addresses are trimmed and rejected if the local or domain part is missing; an empty list email stays unfiltered. update to subscribed asks for confirmation when resuming a subscription; already-subscribed members are left as they are
• set-tags is declarative: tags becomes the full active set and every other tag is removed unless named in preserveTags (static-segment membership is stored as a tag). Returns tagsAdded, tagsRemoved, and tagsActive

mailchimp_upsert_subscriber _tool

• 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" uses Mailchimp's double opt-in flow. New or resumed subscribed status asks for confirmation of documented consent before anything is written; declining writes nothing. Already-subscribed updates and updateExistingStatus: false keep the existing status without asking

mailchimp_find_subscriber _tool

• email accepts an address or free-form search fragment, including a fragment without @, 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 _tool

• 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
• Any row that would be subscribed needs one confirmation before the whole batch writes; declining writes nothing. Pending-only imports need none
• Returns totalCreated, totalUpdated, errorCount, and per-row succeeded and failed entries; incomplete addresses fail as invalid_email, and a batch with no valid rows makes no upstream request

mailchimp_segments _tool

• 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 _tool

• 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 _tool

• Operations: list (filter by status, listId, sinceSendTime / beforeSendTime), get, create (type of regular / plaintext / rss, plus recipients and settings), update, replicate, get-content, set-content, get-checklist, cancel-send, create-resend, pause-rss, resume-rss; all but list and create take campaignId
• set-content accepts html, plainText, templateId + templateSections, archiveContent, url, or localTemplate (exclusive with html and templateId); get-checklist returns isReady and typed items
• get-content accepts variant: html | plainText | archiveHtml | all (default all); empty bodies are omitted
• No send, test, schedule, or delete here; dispatch goes through mailchimp_send_campaign or mailchimp_replicate_campaign

mailchimp_send_campaign _tool

• audienceId, subject, fromName, replyTo, and content (at least one of html, plainText, templateId, localTemplate) required; mode is draft (default), test (needs testEmails, max 50), send, or schedule (needs scheduleTime at least 15 minutes out)
• Returns campaignId, the effective mode, status, recipientCount, webUrl, and non-blocking checklistWarnings; blocking checklist errors throw pre_send_checklist_failed outside draft, and cleanupOnError (default true) deletes the draft after a mid-flow failure
• send and schedule require confirmSend: true, then a single-use confirmation prompt before any campaign is created; declining leaves a draft and sets cancelledByUser. Changed content or a replay asks again, and creation is never retried after an ambiguous upstream failure

mailchimp_replicate_campaign _tool

• sourceCampaignId plus optional subjectOverride, previewTextOverride, fromNameOverride, replyToOverride, titleOverride, audienceOverride, segmentOverride, and contentOverride; mode, testEmails, scheduleTime, and cleanupOnError work as in mailchimp_send_campaign
• Returns the new campaignId, overridesApplied[], and the same status, checklist, and cancelledByUser fields
• Same confirmSend: true plus confirmation-prompt gate for send and schedule

mailchimp_reports _tool

• list (filter by type, sinceSendTime / beforeSendTime), get, or slice with a campaignId and a dimension: abuse-reports, advice, click-details (one URL via linkId), open-details (one member via subscriberHash), domain-performance, eepurl, email-activity, locations, sent-to, unsubscribed
• slice returns rows shaped by the dimension plus totalItems; get throws campaign_not_sent for a campaign with no send

mailchimp_campaign_report _tool

• campaignId plus includeTopN (1–100, default 10) rows per slice
• Returns delivery (delivered, bounces by type, abuse reports), engagement (opens, clicks, unsubscribes), topClickedLinks, topLocations, recentUnsubscribes, and industryBenchmarks when Mailchimp has them; throws campaign_not_sent for a campaign with no send

mailchimp_templates _tool

• list (filter by type of user / base / gallery, category, folderId), get, get-default-content, create, update, and delete; update accepts only name, html, and folderId, so per-section edits go through a campaign's templateSections
• Reads of base and user templates work on free plans; writes and gallery reads need a paid plan and fail as mailchimp_forbidden. mailchimp_local_templates is the authoring path on every plan

mailchimp_files _tool

• list (filter by type, folderId, sinceCreatedAt / beforeCreatedAt), get, upload (name with extension plus base64 fileData, no data: prefix), update (rename, or move with folderId, 0 for root), delete, and read-only list-folders / get-folder; uploads cap at 1 MB per image and 10 MB per other file, and .webp / .avif are not accepted
• upload and get return fullSizeUrl, the public CDN URL to embed in campaign HTML; list adds totalFileSizeInBytes

mailchimp_search _tool

• scope (members or campaigns) and query; audienceId narrows a member search; includeTopN (1–100, default 10) caps each result array
• Members return as exact and fuzzy with upstream totalExact / totalFuzzy; campaigns as matches with a snippet and totalMatches; an empty result carries a note

mailchimp_assets _tool

• list, info (by relPath; returns sha256 and any cached upload), sync (uploads uncached files ahead of a send; returns uploaded, cached, and skipped with reasons), and clear-cache
• @assets/<path> references in content passed to mailchimp_send_campaign, mailchimp_replicate_campaign, or mailchimp_campaigns set-content upload to File Manager and are rewritten to CDN URLs. Uploads are cached by SHA-256 in <assetsDir>/.mailchimp-cache.json; oversize files and paths outside the directory are rejected before upload
• Listed only when MAILCHIMP_ASSETS_DIR is set

mailchimp_local_templates _tool

• list, get (source plus parsed metadata), render-preview (name plus vars; returns HTML, sends nothing), and seed-from-mailchimp (writes Mailchimp template mailchimpTemplateId to disk as name)
• Templates are .eta files with optional YAML frontmatter for subject, previewText, and vars; a declared var left unsupplied fails the render. Campaign tools render one via content.localTemplate + content.localTemplateVars, exclusive with html and templateId. Example templates
• Listed only when MAILCHIMP_TEMPLATES_DIR is set

mailchimp_playbook _tool

• topic: send, post-send-review, deliverability, list-hygiene, onboarding, subscriber-triage, or design-campaign; audienceId for send / list-hygiene / design-campaign, campaignId for post-send-review, email for subscriber-triage
• Returns markdown instructions tuned to live numbers, a liveState snapshot, and nextToolSuggestions with pre-filled inputs; makes no writes

mailchimp://account _resource

• No parameters; application/json with profile, plan, data center, total subscribers, and fetchedAt
• Same data as mailchimp_account operation: info

mailchimp://audiences/{audienceId} _resource

• Name, contact, stats, campaign defaults, permission reminder, double opt-in status, and subscribe URL
• audienceId comes from mailchimp_audiences operation: list

mailchimp://campaigns/{campaignId} _resource

• Status, settings, recipients, tracking, and report summary
• campaignId comes from mailchimp_campaigns operation: list

mailchimp://campaigns/{campaignId}/report _resource

• Emails sent, bounces, opens, clicks, unsubscribes, abuse reports, and industry stats
• Fails with a validation error until the campaign has been sent

newsletter_from_source _prompt

• Arguments: source (URL or free-form brief) required; audienceId and seasonalContext optional
• Returns one user message that chains mailchimp_playbook (topic: design-campaign) into an HTML draft, then draft, test, and send via mailchimp_send_campaign

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

Mailchimp-specific:

• Marketing API v3 client that derives the API host and data center from the key's -<dc> suffix, with retries, a process-wide concurrency limit (MAILCHIMP_CONCURRENCY_LIMIT), and a cooldown after a 429
• Send gates: campaigns default to draft, send / schedule need confirmSend: true plus a confirmation prompt, and new or resumed subscribed subscriptions need confirmation too; imports default to pending
• No irreversible deletes: removing audiences, merge fields, or campaigns, and permanently deleting subscribers, stay in the Mailchimp UI; archive is the strongest subscriber removal
• Local authoring: @assets/<path> files upload and rewrite at send time, and .eta templates render locally, which covers free plans where the Templates API is read-only
• List operations page with count (max 1000) and offset

Agent-friendly output:

• Explained empties: note / notes[] on empty activity feeds, audience overviews, and searches say whether data is missing or genuinely zero
• Partial failure: mailchimp_import_subscribers and mailchimp_segments batch-update-members return per-row successes and errors instead of failing the batch
• Discriminated outputs: operation, dimension, and mode say which fields are populated; isNew and cancelledByUser report what actually happened
• Typed errors: every declared reason (campaign_not_sent, pre_send_checklist_failed, mailchimp_forbidden, …) carries a recovery hint for the caller's next move

Getting started

Add the following to your MCP client configuration file. See docs/api-key.md for how to generate a Mailchimp API key.

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

Or with npx (no Bun required):

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

Or with 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"
      ]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

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

Prerequisites

• Bun v1.4.0 or higher (or Node.js v24+).
• A Mailchimp Marketing API key. Its -dc suffix (e.g. -us22) identifies your data center and is parsed at startup.

Installation

1. Clone the repository:

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

1. Navigate into the directory:

cd mailchimp-mcp-server

1. Install dependencies:

bun install

1. Configure environment:

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

Configuration

See .env.example for the full list of optional overrides.

Running the server

Local development

• Watch mode (transport via MCP_TRANSPORT_TYPE):

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

• Build and run:

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

• Run checks and tests:

  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

The Dockerfile defaults to HTTP transport, stateful session mode, and logs to /var/log/mailchimp-mcp-server. OpenTelemetry peer dependencies are installed by default; build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic
• Use ctx.log for request-scoped logging
• Register new tools and resources via the barrels in src/mcp-server/*/definitions/index.ts
• Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.