Tools

Seventeen tools grouped by shape — 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.

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

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.

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool, resource, and prompt definitions — single file per primitive, framework handles registration and validation
• Unified error handling — handlers throw, framework catches, classifies, and formats
• Pluggable auth: none, jwt, oauth
• Structured logging with optional OpenTelemetry tracing
• STDIO and Streamable HTTP transports

Mailchimp-specific:

• Auto-derives the API base URL from the -dc suffix on the API key
• Safe-by-default send workflows — elicit confirmation, pending-status imports, no permanent deletes from agent surface
• Workflow tools parallelize related sub-requests under a configurable concurrency limit
• Domain normalization shapes sparse upstream payloads into compact, LLM-friendly output without fabricating values

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": {
      "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": {
      "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": {
      "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.3.2 or higher (or Node.js v22+).
• A Mailchimp Marketing API key — the key's -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

2. Navigate into the directory:

cd mailchimp-mcp-server

3. Install dependencies:

bun install

4. 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

• Hot-reload dev mode:

  bun run dev:stdio
  bun run dev:http
  

• Build and run the production version:

  # One-time build
  bun run rebuild
  
  # Run the built server
  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, stateless 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 and pull requests are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.