Mailchimp MCP Server

A Model Context Protocol (MCP) server exposing read-only access to the Mailchimp Marketing API v3 through 18 tools covering 103 endpoints — audiences, members, campaigns, reports, automations, templates, landing pages, e-commerce, and account administration.

Tools are grouped by domain and dispatch on an action parameter, so the full API surface stays reachable while the tool count stays low enough for hosts that cap actions per agent (Microsoft Copilot Studio among them).

Every tool issues a GET. The server has no code path that can create, modify, or delete anything in your Mailchimp account, or send email.

Usage

{
  "mcpServers": {
    "mailchimp": {
      "command": "npx",
      "args": ["@agentx-ai/mailchimp-mcp-server"],
      "env": {
        "MAILCHIMP_API_KEY": "your-api-key-here"
      }
    }
  }
}

Local installation

npm install     # installs deps and builds
npm run dev     # build + open the MCP Inspector

Other scripts: npm run build (compile), npm start (raw stdio server), npm run watch (recompile on change), npm run inspector (Inspector against the existing build).

Configuration

MAILCHIMP_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-us14

A .env file in the project root is read automatically. The key must keep its data-center suffix (-us1, -us14, …) — it determines the API hostname. The server refuses to start without a valid suffix rather than failing later with an opaque DNS error.

Transports

Both transports serve the identical tool surface from one server definition (src/server.ts), so they cannot drift apart.

stdio (default) — for Claude Desktop, Cursor, the MCP Inspector, and any local client:

npm start

Streamable HTTP — for network-based hosts such as Microsoft Copilot Studio:

npm run start:http          # or: node build/index.js --http

HTTP mode also activates automatically when PORT is set, which is how Azure App Service, Container Apps, and most PaaS hosts signal that they expect a listener.

Variable	Default	Purpose
MAILCHIMP_API_KEY	—	Required. Must keep its data-center suffix.
PORT	3000	HTTP port. Setting it enables HTTP mode.
HOST	0.0.0.0	Bind address.
MCP_PATH	/mcp	Endpoint path.
MCP_AUTH_TOKEN	—	When set, /mcp requires Authorization: Bearer <token>.
MCP_TRANSPORT	stdio	Set to http to force HTTP mode.

GET /health returns server name, version, endpoint path, and whether auth is required — use it as your platform's health probe.

Set MCP_AUTH_TOKEN before exposing this server publicly. The endpoint grants read access to your entire Mailchimp account, and there is no other access control in front of it. The server logs a warning at startup when the token is unset. Compare is constant-time, so the token is not vulnerable to timing analysis.

Sessions are stateless: each request gets its own server and transport instance, so the process scales horizontally with no shared session store.

Microsoft Copilot Studio

1. Deploy this server somewhere with a public HTTPS URL (Azure Container Apps, App Service, or any container host). Set MAILCHIMP_API_KEY and MCP_AUTH_TOKEN in its environment.
2. Confirm https://<your-host>/health returns {"status":"ok"}.
3. In Copilot Studio, add a new tool → Model Context Protocol, pointing at https://<your-host>/mcp.
4. Configure authentication as a bearer token and supply the same value as MCP_AUTH_TOKEN.
5. All 18 tools appear as agent actions. The tool count is deliberately kept low because Copilot Studio limits actions per agent — the action parameter is what preserves access to all 103 endpoints.

Tool catalog

Tool	Actions	Covers
mailchimp_account	11	ping, account overview, authorized apps, verified domains, batches, connected sites, chimp chatter
mailchimp_search	2	members, campaigns
mailchimp_audiences	12	lists, growth history, activity, client stats, location stats, abuse reports, signup forms, webhooks, merge fields
mailchimp_audience_groups	7	segments, segment members, interest categories, interests
mailchimp_members	9	members, tags, activity, activity feed, events, notes, goals
mailchimp_campaigns	5	campaigns, content, feedback, send checklist
mailchimp_reports	16	summary, advice, opens, clicks, link clickers, unsubscribes, abuse, sent-to, domain performance, locations, eepurl, sub-reports, email activity, product activity
mailchimp_automations	7	workflows, emails, queues, removed subscribers
mailchimp_templates	3	templates, default content
mailchimp_files	6	File Manager files and folders, campaign folders
mailchimp_landing_pages	3	pages, content
mailchimp_conversations	3	conversations, messages
mailchimp_stores	3	stores, account-wide orders
mailchimp_products	4	products, variants
mailchimp_orders	3	orders, line items
mailchimp_customers	2	customers
mailchimp_carts	3	carts, line items
mailchimp_promos	4	promo rules, promo codes

Each tool's description lists its actions and what each one needs. Run npm run dev and open the Inspector's Tools tab to see the full schemas.

Conventions

Every tool follows the same shape, so the catalog above is enough to predict any call:

• action is always required and selects the data to retrieve. An invalid action returns an error listing the valid ones.
• List-style actions return a summary envelope — { total_items, returned, items: [...] } — where each item is trimmed to identifying fields. This keeps a 1000-row page from flooding the model's context, while total_items tells the caller whether more rows exist.
• Detail-style actions (details, summary, single-record lookups) return the complete raw Mailchimp record, unmodified.
• Paging: collection tools accept count (1–1000, default 1000) and offset. To read an audience larger than 1000, call repeatedly with offset 0, 1000, 2000, … until returned is less than count.
• IDs: start at mailchimp_audiences action=list, mailchimp_campaigns action=list, or mailchimp_stores action=list. mailchimp_search action=members is the fastest route to a subscriber_hash.
• Missing arguments are rejected before any HTTP request, with a message naming exactly which ones the chosen action needs.

Development

npm run build      # tsc
npm run watch      # tsc --watch
npm run inspector  # MCP Inspector against build/index.js

There is no test suite in this repository.

Known gaps

• Customer journeys are not readable. Mailchimp does not expose them via the Marketing API; the automation tools cover classic automations only.
• Endpoint coverage is based on the documented Marketing API v3 surface and has not been exercised against a live account for all 103 actions. The transport, dispatch, and validation layers are verified; individual endpoint URLs are not.
• No deployment manifests. There is no Dockerfile or IaC in this repo; hosting is left to you.

API reference

https://mailchimp.com/developer/marketing/api/

License

MIT.