Mailchimp MCP Server

The most complete Model Context Protocol (MCP) server for the Mailchimp Marketing API: 227 tools to query and manage your Mailchimp account from any MCP-compatible client. It covers the full campaign, audience, member, segment, automation and reporting surface, complete e-commerce (read and write), landing pages, File Manager, surveys, signup forms and verified domains, plus multi-account support and runtime-security guardrails (read-only, dry-run and audit modes, with per-tool risk metadata).

Uses the Mailchimp Marketing API via `requests`. Not based on the official mailchimp-marketing-python client. I hit too many issues with it so I went with raw HTTP calls instead.

Quick start

uvx mailchimp-mcp   # no install required; just needs MAILCHIMP_API_KEY

Add it to your MCP client (Claude Desktop, Cursor, Cline, …):

{
  "mcpServers": {
    "mailchimp": {
      "command": "uvx",
      "args": ["mailchimp-mcp"],
      "env": {
        "MAILCHIMP_API_KEY": "your-key-us8",
        "MAILCHIMP_READ_ONLY": "true"
      }
    }
  }
}

Tip: start with `MAILCHIMP_READ_ONLY=true` to explore safely, then flip it off when you are ready to write. See Configuration for all options.

Docker

A prebuilt image is published to the GitHub Container Registry on every release:

docker run --rm -i -e MAILCHIMP_API_KEY=your-key-us8 ghcr.io/damientilman/mailchimp-mcp-server:latest

Or point your MCP client at it:

{
  "mcpServers": {
    "mailchimp": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "MAILCHIMP_API_KEY", "-e", "MAILCHIMP_READ_ONLY", "ghcr.io/damientilman/mailchimp-mcp-server:latest"],
      "env": {
        "MAILCHIMP_API_KEY": "your-key-us8",
        "MAILCHIMP_READ_ONLY": "true"
      }
    }
  }
}

Features

Read

• Campaigns - List, search, and inspect campaign details
• Reports - Open/click rates, bounces, per-link clicks, domain performance, unsubscribe details
• Email activity - Per-recipient open/click tracking, member activity history
• Audiences - Browse audiences, members, segments, tags, and growth history
• Merge fields - List custom fields for an audience
• Interest categories & groups - Browse interest categories and options
• Webhooks - List configured webhooks
• Segments - Get segment details, conditions, and member lists
• Automations - List workflows, inspect emails in a workflow, view queues
• Templates - Browse templates and extract HTML content
• Landing pages - List and inspect landing pages
• File Manager - Browse stored images and files, and folders
• Surveys - List and inspect an audience's surveys
• Signup forms - Inspect an audience's signup forms
• E-commerce - Stores, orders, products, customers (requires e-commerce integration)
• Campaign folders - Browse folder organization
• Batch operations - Monitor bulk operation status

Write

• Members - Add, update, unsubscribe, delete, and tag contacts
• Audiences - Batch subscribe members, update audience settings
• Campaigns - Create drafts, set HTML content, schedule, unschedule, duplicate, delete, send, send test, cancel
• Segments/Tags - Create, update, delete, add/remove members, dynamic conditions
• Merge fields - Create, update, delete custom fields
• Interest categories - Create and delete categories and interests
• Webhooks - Create and delete webhooks
• Templates - Create, update, and delete email templates
• File Manager - Upload (base64) and delete images and files
• Surveys - Publish and unpublish audience surveys
• Signup forms - Customize header, contents, and styles
• Automations - Pause and start automation workflows
• E-commerce - Cart lifecycle, promo rules, and promo codes for discount workflows
• Batch - Run bulk API operations in a single request

Runtime security

• Risk metadata - Per-tool read / write / destructive classification via MCP annotations and `describe_tools`
• Audit log - Optional structured JSON audit events per dispatch (`MAILCHIMP_AUDIT_LOG`)
• Argument validation - Pagination caps and required-ID checks before every request

Prerequisites

• Python 3.10+
• A Mailchimp API key

Installation

Using `uvx` (recommended)

No installation needed — run directly:

uvx mailchimp-mcp

Using `pip`

pip install mailchimp-mcp

Then run:

mailchimp-mcp

From source

git clone https://github.com/damientilman/mailchimp-mcp-server.git
cd mailchimp-mcp-server
python -m venv .venv
source .venv/bin/activate
pip install -e .

Configuration

The datacenter (`us8`, `us21`, etc.) is automatically extracted from each key.

Safety modes

Read-only mode — When `MAILCHIMP_READ_ONLY=true`, all write tools (create, update, delete, schedule, etc.) are blocked and return an error. Read tools work normally. This is the recommended default for shared or exploratory setups where you only need reporting and analytics.

Dry-run mode — When `MAILCHIMP_DRY_RUN=true`, write tools return a preview of the action they *would* perform (tool name, target resource, parameters, and its risk tier) without making any API call. Useful for testing prompts before going live.

Runtime security

The server is designed for defense-in-depth alongside an external MCP gateway: it owns the *semantics* (which tools are reads, reversible writes, or irreversible) and exposes them as machine-readable signals a gateway can enforce on, rather than making the gateway guess which calls are dangerous.

Risk metadata — Every tool is classified as `read`, `write`, or `destructive` (irreversible data loss or an irreversible send). This surfaces two ways:

• MCP tool annotations — `readOnlyHint`, `destructiveHint`, and `idempotentHint` travel through the standard `tools/list`, so any compliant client or gateway reads them directly.
• `describe_tools` — a read tool returning `{name, risk, read_only, destructive, idempotent}` for every tool plus per-tier counts, for gateways that prefer a tool call.

Structured audit log — With `MAILCHIMP_AUDIT_LOG=true`, each dispatch emits one JSON event to stderr with the tool, its risk tier, the `destructive` flag, the target account, the outcome (`executed` / `blocked_read_only` / `dry_run`), and the inspected arguments. Bulky or sensitive values (e.g. base64 `file_data`) are redacted and response bodies are never logged, so the stream is a safe audit sink to tail centrally.

Argument-contract validation — All writes funnel through a single `_guard_write` chokepoint, and every request is validated before dispatch (pagination `count` capped to 1–1000, missing path IDs rejected), so malformed calls fail fast and consistently instead of hitting the API.

Tool profiles

Exposing all 227 tools sends a large tool list to the model on every turn (~63k tokens). If you only need part of the surface, load a subset with one line:

"env": { "MAILCHIMP_API_KEY": "your-key-us8", "MAILCHIMP_TOOLS": "read" }

`MAILCHIMP_TOOLS` accepts a comma-separated mix of risk tiers (`read`, `write`, `destructive`) and/or exact tool names; a tool is kept if either matches. Unset (or `all`) exposes everything.

• `read` — reporting and analytics only (~115 tools, ~29k tokens). A safe, lightweight default for exploration.
• `read,write` — everything except irreversible tools.
• `list_campaigns,get_campaign_report,send_campaign` — a hand-picked minimal set.

Tool descriptions are also trimmed of repeated boilerplate before they reach the model, so even the full set is leaner than the raw docstrings. Use `describe_tools` to see each tool's risk tier.

Multi-account

By default the server uses the single `MAILCHIMP_API_KEY`, exposed as the `default` account. To manage several Mailchimp accounts from one server, add `MAILCHIMP_API_KEY_` variables — the suffix becomes the lowercased account name (e.g. `MAILCHIMP_API_KEY_MARKETING` → `marketing`).

Every tool then accepts an optional `account` argument, e.g. `list_audiences(account="marketing")`. Selection is per call and stateless — there is no "current account" to switch, so a write always names its target. Omitting `account` uses `default`. Call `list_accounts` to see the configured names and their safety-flag state, and each account can carry its own `MAILCHIMP_READ_ONLY_` / `MAILCHIMP_DRY_RUN_` flags (so a write-protected account and a writable one can live side by side). An unknown `account` returns an error listing the configured names.

Single-key setups are unaffected: with only `MAILCHIMP_API_KEY` set, nothing changes.

{
  "mcpServers": {
    "mailchimp": {
      "command": "uvx",
      "args": ["mailchimp-mcp"],
      "env": {
        "MAILCHIMP_API_KEY": "your-default-key-us8",
        "MAILCHIMP_API_KEY_MARKETING": "another-key-us5",
        "MAILCHIMP_READ_ONLY_MARKETING": "true"
      }
    }
  }
}

MCP client configuration

Most MCP clients accept a JSON configuration block describing how to launch the server.

Configure yours to invoke `uvx mailchimp-mcp` (or `mailchimp-mcp` if installed via pip)

with `MAILCHIMP_API_KEY` exported in the environment.

Using uvx (recommended)

{
  "mcpServers": {
    "mailchimp": {
      "command": "uvx",
      "args": ["mailchimp-mcp"],
      "env": {
        "MAILCHIMP_API_KEY": "your-api-key-here"
      }
    }
  }
}

Using pip install

{
  "mcpServers": {
    "mailchimp": {
      "command": "mailchimp-mcp",
      "env": {
        "MAILCHIMP_API_KEY": "your-api-key-here"
      }
    }
  }
}

Read-only mode (recommended for exploration)

{
  "mcpServers": {
    "mailchimp": {
      "command": "uvx",
      "args": ["mailchimp-mcp"],
      "env": {
        "MAILCHIMP_API_KEY": "your-api-key-here",
        "MAILCHIMP_READ_ONLY": "true"
      }
    }
  }
}

CLI-based clients

If your MCP client provides a CLI to register servers, the equivalent invocation is:

mcp-cli add mailchimp \
  -e MAILCHIMP_API_KEY=your-api-key-here \
  -- uvx mailchimp-mcp

Replace `mcp-cli` with your client's binary name. For read-only mode, add

`-e MAILCHIMP_READ_ONLY=true` to the command.

Available Tools

Account

Campaigns (read)

Campaign Reports

Campaigns (write)

Audiences (read)

Members (read)

Members (write)

Audiences (write)

Segments & Tags

Merge Fields

Interest Categories & Groups

Webhooks

Automations & Customer Journeys

> Mailchimp does not expose a public read API for Customer Journeys (only the trigger endpoint above). The `search_automation_campaigns`, `get_member_journey_events` and `get_automation_summary` tools provide the recommended workarounds — they surface every campaign emitted by automations or journeys, even though the journey graph itself remains private.

Templates

Landing Pages

File Manager

Surveys

Signup Forms

E-commerce

E-commerce Carts

E-commerce Promo Rules & Codes

Batch Operations

Verified Domains

Connected Sites & Account

Folders

Campaign Extras (checklist, collaboration, RSS)

Audience Insights & Deliverability

Members (compliance & advanced)

Automation Emails (single-email control)

Reporting (extras)

E-commerce (write)

Example Prompts

Once connected, you can ask your MCP client to perform requests like:

• *"Show me all my sent campaigns from the last 3 months"*
• *"What was the open rate and click rate for my last newsletter?"*
• *"How many subscribers did I gain this year?"*
• *"Which links got the most clicks in campaign X?"*
• *"Search for subscriber john@example.com"*
• *"Add tag 'VIP' to all members who opened my last campaign"*
• *"Create a draft campaign for my main audience with subject 'March Update'"*
• *"Create a campaign targeting only my VIP segment"*
• *"Send a test email of my draft campaign to test@example.com"*
• *"List all merge fields for my main audience"*
• *"Create a dropdown merge field called 'Industry' with options Tech, Finance, Healthcare"*
• *"Create a dynamic segment of members where FNAME is John"*
• *"Batch subscribe 50 members from this CSV data"*
• *"Set up a webhook to notify my app when new subscribers join"*
• *"Unsubscribe user@example.com from my list"*
• *"Show me the domain performance breakdown for my last campaign"*
• *"Where in the world did people open my newsletter? Show me the geographic breakdown."*
• *"Create an A/B test campaign with two subject lines and pick the winner by opens after 24 hours"*
• *"What advice does Mailchimp have for improving my last campaign?"*
• *"Pause my welcome automation"*
• *"List all orders from my Shopify store this month"*

Workflow recipes

Multi-step requests that chain tools end to end:

• Weekly performance review — *"Summarise my last week: list campaigns sent since Monday, pull each report, and rank them by click rate with one takeaway each."* Chains `search_campaigns` → `get_campaign_report` → `get_campaign_advice`.
• Deliverability audit — *"Check my sending health: are my domains verified, any spam complaints on recent campaigns, and how did the last one perform by recipient domain?"* Chains `list_verified_domains` → `get_campaign_abuse_reports` → `get_domain_performance`.
• Re-engagement — *"Find everyone who didn't open my last newsletter and resend it with a new subject line."* Chains `get_campaign_report` → `resend_to_non_openers`.
• Safe send — *"Dry-run a campaign to my VIP segment, show me the send checklist, then send it once I confirm."* With `MAILCHIMP_DRY_RUN=true`, previews via `create_campaign` → `get_campaign_send_checklist` → `send_campaign`.
• Agencies (multi-account) — *"For both the `acme` and `globex` accounts, list this month's top campaign by open rate."* Passes `account="acme"` / `account="globex"` per call. See Multi-account.

Contributing

Contributions are welcome. See CONTRIBUTING.md for development setup,

test instructions, and pull request guidelines.

Security

If you find a security vulnerability, please follow the responsible disclosure process

described in SECURITY.md.

Changelog

See CHANGELOG.md for the full release history.

Author

Built by Damien Tilman — damien@tilman.marketing

License

MIT — see LICENSE for details.