mailchimp-mcp

12 tools. 282 endpoints. Zero bloat.

A hybrid Mailchimp MCP server built on the architecture Cloudflare pioneered for their own API: instead of drowning the model in 50+ tool definitions, we give it 10 fast native tools for the email workflow you actually use, plus two universal tools that unlock the entire Mailchimp Marketing API on demand.

The Problem with Every Other Mailchimp MCP

There are half a dozen Mailchimp MCP servers on GitHub. They all do the same thing: expose 40–50+ individual tools, one per API operation. list_campaigns, get_campaign, create_campaign, delete_campaign, list_audiences, get_audience, add_member, update_member... on and on.

Every single one of those tool definitions gets loaded into the LLM's context window on every turn of every conversation — even when you're talking about something completely unrelated to Mailchimp. That's thousands of tokens burned before the model even starts thinking about your question.

This is the context flooding problem. Cloudflare ran the math on their own API (2,500+ endpoints) and found that exposing everything as native MCP tools would consume 1.17 million tokens per turn. Even aggressively pruned, it was 244,000 tokens. Their solution was radical: collapse the entire API surface into just two tools — search and execute — and let the model discover what it needs on the fly. They called it Code Mode, and it reduced the footprint to ~1,000 tokens.

Related MCP server: Mailchimp MCP Server

Our Take: The Hybrid Architecture

Pure Code Mode is elegant, but it has a tradeoff. For the stuff you do every single day — list your audiences, create a campaign, check open rates — forcing the model to search the API catalog first adds an unnecessary round trip. You already know what you want. The model should too.

The deeper analysis of real-world API traffic reveals a consistent pattern: a Pareto distribution. The vast majority of what people actually do hits a tiny subset of endpoints. The long tail is everything else.

So we built a hybrid:

Layer 1: 10 native tools for the mass email workflow. These are purpose-built, zero-overhead, and handle the 80% case. Creating a campaign, sending it, checking the report — one tool call, done. No searching, no discovering, no extra turns.

Layer 2: search + execute for everything else. An embedded catalog of all 282 Mailchimp API endpoints, generated from the official OpenAPI spec. The model searches to discover endpoints, then executes to call them. Automations, e-commerce, landing pages, file management, batch operations — it's all there without adding a single extra tool definition.

The result: 12 tool schemas in your context window instead of 50+. Fast for the common case, omnipotent for the edge case.

Setup

Get Your Mailchimp API Key

1. Log in to Mailchimp

2. Go to Profile → Extras → API keys

3. Click Create A Key

4. Copy the key — it looks like: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-usXX

The suffix after the dash (us12, us6, etc.) is your data center. The server extracts it automatically.

Claude Code

Add to your ~/.claude.json (or project-level .claude.json) under mcpServers:

{
  "mcpServers": {
    "mailchimp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mailchimp-mcp"],
      "env": {
        "MAILCHIMP_API_KEY": "your-api-key-us12"
      }
    }
  }
}

Restart Claude Code for the server to connect. You'll see mailchimp in your MCP server list, and the tools will appear as mcp__mailchimp__list_audiences, mcp__mailchimp__search, etc.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "mailchimp": {
      "command": "npx",
      "args": ["-y", "mailchimp-mcp"],
      "env": {
        "MAILCHIMP_API_KEY": "your-api-key-us12"
      }
    }
  }
}

Restart Claude Desktop. The Mailchimp tools will appear in the tools menu (hammer icon).

Cursor / Windsurf / Other MCP Clients

The config pattern is the same — npx -y mailchimp-mcp as the command, with your API key in the env block. Consult your client's MCP documentation for where to place the config.

Running from Source (Development)

If you cloned the repo instead of using npx:

{
  "mcpServers": {
    "mailchimp": {
      "command": "node",
      "args": ["/path/to/mailchimp-mcp/dist/index.js"],
      "env": {
        "MAILCHIMP_API_KEY": "your-api-key-us12"
      }
    }
  }
}

Native Tools: The Fast Path

These 10 tools cover the complete mass email lifecycle — no searching required:

Example: End-to-End Campaign

1. list_audiences()                                          → find your audience ID
2. list_templates(type: "user")                              → find a template
3. create_campaign(list_id, subject, from_name, reply_to)    → get a campaign_id back
4. update_campaign_content(campaign_id, template_id: 123)    → set the email content
5. send_campaign(campaign_id)                                → fire it off
6. get_campaign_report(campaign_id)                          → check opens & clicks

Example: Add a Subscriber

add_or_update_member(
  list_id: "abc123",
  email: "jane@example.com",
  merge_fields: { "FNAME": "Jane", "LNAME": "Doe" },
  tags: ["VIP", "2026-spring"]
)

The MD5 subscriber hash that Mailchimp requires is computed automatically from the email — you never have to think about it.

Universal Tools: The Long Tail

For anything beyond the 10 native tools — automations, e-commerce, segments, webhooks, landing pages, file uploads, batch operations, and hundreds more — use search and execute.

Search: Discover What's Available

Call with no arguments to see the full API map:

> search()

Mailchimp Marketing API — 282 endpoints across 29 categories

  lists (66) — Audiences, members, segments, merge fields, tags, webhooks, signups
  ecommerce (60) — Stores, products, orders, carts, customers
  campaigns (22) — Email campaigns — create, schedule, send, content, feedback
  reports (22) — Campaign performance reports — opens, clicks, bounces
  automations (18) — Marketing automation workflows and triggered emails
  ...

Narrow it down:

> search(tag: "automations")
> search(query: "segment members")
> search(query: "merge fields", method: "POST")

Execute: Call Any Endpoint

> execute(method: "GET", path: "/ping")
{ "health_status": "Everything's Chimpy!" }

> execute(method: "GET", path: "/automations", params: { "count": "5" })

> execute(method: "POST", path: "/lists/{list_id}/segments", body: {
    "name": "Active subscribers",
    "static_segment": ["email1@test.com", "email2@test.com"]
  })

All 29 API Categories

Development

git clone https://github.com/livemau5/mailchimp-mcp.git
cd mailchimp-mcp
npm install
npm run build

# Regenerate the API catalog from the latest Mailchimp spec
npm run generate-catalog

# Run in development mode
MAILCHIMP_API_KEY=your-key-us12 npm run dev

Project Structure

src/
  index.ts              Entry point — server setup, tool registration, stdio transport
  types.ts              CatalogEntry interface
  utils.ts              Data center extraction, URL building, auth, response formatting
  api-catalog.ts        Auto-generated catalog of all 282 endpoints
  tools/
    native.ts           10 native tools for the mass email workflow
    search.ts           Search tool — text/tag/method filtering over the catalog
    execute.ts          Execute tool — HTTP client with automatic Basic Auth
scripts/
  generate-catalog.ts   Parses official Mailchimp OpenAPI spec into api-catalog.ts

License

MIT