# Mailchimp MCP Server

[![npm version](https://img.shields.io/npm/v/@agentx-ai/mailchimp-mcp-server)](https://www.npmjs.com/package/@agentx-ai/mailchimp-mcp-server)

[![Watch the Notion Tutorial video](https://img.shields.io/badge/Watch_on-YouTube-red?logo=youtube&style=for-the-badge)](https://youtu.be/YcUrRAnFp8Q)
[![Website](https://img.shields.io/badge/Website-🌐-purple)](https://www.agentx.so/mcp/mailchimp)

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

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

## Local installation

```bash
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

```bash
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:

```bash
npm start
```

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

```bash
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

```bash
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.