> **🚀 Don't want to self-host?** [Join the waitlist for our fully managed solution →](https://mcpengage.com/mailchimp)
> 
> Zero setup. Zero maintenance. Just connect and automate.

---

# 📧 Mailchimp MCP Server

## 💡 What This Unlocks

**This MCP server gives AI direct access to your entire Mailchimp marketing operation.** Instead of clicking through campaigns and lists, you just *tell* it what you need.

### 🎯 Mailchimp-Native Power Moves

| Just say... | What happens |
|-------------|--------------|
| *"Show me subscribers who opened the last campaign but didn't click"* | Queries campaign reports, filters engaged users, returns contact list with engagement scores |
| *"Create a welcome email campaign for new subscribers with 15% off code"* | Builds campaign, designs template, adds coupon, schedules send |
| *"Which audience segments have the highest open rates this month?"* | Pulls analytics, compares segment performance, generates ranked report |
| *"Add everyone from webinar-attendees.csv to the VIP list and tag them"* | Imports contacts, assigns to audience, applies tags, updates preferences |
| *"Draft a product launch email and schedule for Thursday 9am EST"* | Creates campaign, generates content, sets timezone, schedules delivery |

### 🔗 The Real Power: Combining Tools

AI can chain multiple Mailchimp operations together:

- **Smart Segmentation:** *"Find subscribers who joined in the last 30 days and have opened at least 2 emails"* → Query audiences, filter by join date and engagement, create segment
- **Campaign Optimization:** *"Compare subject lines from my last 5 campaigns and suggest improvements for tomorrow's send"* → Pull campaign data, analyze open rates, generate recommendations
- **List Health:** *"Show me contacts who haven't engaged in 90 days and create a re-engagement campaign"* → Identify inactive users, build win-back sequence, schedule drip

## 📦 What's Inside

**85 API tools** covering the entire Mailchimp platform:

- **Campaigns** — Create, send, schedule, test, and analyze email campaigns
- **Audiences** — Manage lists, segments, merge fields, and tags
- **Contacts** — Add, update, delete, and search subscribers
- **Templates** — Design and manage email templates
- **Automations** — Set up drip campaigns and triggered emails
- **Reports** — Campaign analytics, engagement metrics, revenue tracking

All with proper error handling, automatic rate limiting, and TypeScript types.

## 🚀 Quick Start

### Option 1: Claude Desktop (Local)

1. **Clone and build:**
   ```bash
   git clone https://github.com/YOUR_USERNAME/mailchimp-mcp.git
   cd mailchimp-mcp
   npm install
   npm run build
   ```

2. **Get your Mailchimp API key:**
   - Go to [Mailchimp Account Settings](https://admin.mailchimp.com/account/api/)
   - Click "Create A Key"
   - Copy the API key (starts with your username and ends with `-us##`)

3. **Configure Claude Desktop:**
   
   On macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
   
   On Windows: `%APPDATA%\Claude\claude_desktop_config.json`

   ```json
   {
     "mcpServers": {
       "mailchimp": {
         "command": "node",
         "args": ["/ABSOLUTE/PATH/TO/mailchimp-mcp/dist/index.js"],
         "env": {
           "MAILCHIMP_API_KEY": "your-api-key-here"
         }
       }
     }
   }
   ```

4. **Restart Claude Desktop**

### Option 2: Deploy to Railway

[![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/template/mailchimp-mcp)

1. Click the button above
2. Set `MAILCHIMP_API_KEY` in Railway dashboard
3. Use the Railway URL as your MCP server endpoint

### Option 3: Docker

```bash
docker build -t mailchimp-mcp .
docker run -p 3000:3000 \
  -e MAILCHIMP_API_KEY=your-api-key \
  mailchimp-mcp
```

## 🔐 Authentication

Mailchimp uses API key authentication:

1. **Log in to Mailchimp**
2. **Navigate to:** Account → Extras → API Keys
3. **Click:** "Create A Key"
4. **Copy the key** (format: `username-md5hash-us##`)

The API key includes your datacenter (e.g., `us19`) — the MCP server automatically extracts this.

## 📚 Available Tools

### Campaigns

- `list_campaigns` — List email campaigns with filtering by status, type, folder
- `get_campaign` — Get campaign details including content and settings
- `create_campaign` — Create new email campaigns (regular, automated, RSS)
- `update_campaign` — Update campaign settings, content, or subject lines
- `send_campaign` — Send campaign immediately or schedule for later
- `schedule_campaign` — Schedule campaign for specific date/time
- `pause_campaign` — Pause a scheduled campaign
- `replicate_campaign` — Duplicate an existing campaign
- `cancel_campaign` — Cancel a scheduled or sending campaign
- `get_campaign_content` — Get campaign HTML and text content
- `update_campaign_content` — Update campaign body content

### Campaign Reports

- `get_campaign_report` — Get detailed campaign performance metrics
- `list_campaign_reports` — List reports for multiple campaigns
- `get_unsubscribed` — List contacts who unsubscribed from campaign
- `get_click_details` — Get link-by-link click tracking
- `get_email_activity` — Get subscriber-level email activity

### Audiences (Lists)

- `list_audiences` — List all audiences/lists
- `get_audience` — Get audience details and stats
- `create_audience` — Create new audience/list
- `update_audience` — Update audience settings
- `delete_audience` — Delete an audience
- `batch_subscribe` — Add multiple contacts in one call
- `batch_unsubscribe` — Remove multiple contacts

### Contacts (Members)

- `list_contacts` — List contacts in an audience with filtering
- `get_contact` — Get detailed contact information
- `add_contact` — Add new subscriber to audience
- `update_contact` — Update contact details, tags, or merge fields
- `delete_contact` — Remove contact permanently
- `archive_contact` — Archive (soft delete) a contact
- `search_contacts` — Search across all audiences
- `add_contact_tag` — Apply tags to contacts
- `remove_contact_tag` — Remove tags from contacts

### Segments

- `list_segments` — List audience segments
- `get_segment` — Get segment details and member count
- `create_segment` — Create new segment with conditions
- `update_segment` — Update segment name or conditions
- `delete_segment` — Remove a segment
- `list_segment_members` — List contacts in a segment

### Templates

- `list_templates` — List email templates
- `get_template` — Get template details and HTML
- `create_template` — Create new template
- `update_template` — Update template content
- `delete_template` — Remove template

### Automations

- `list_automations` — List automated workflows
- `get_automation` — Get automation details
- `pause_automation` — Pause an automation
- `start_automation` — Start a paused automation
- `list_automation_emails` — List emails in workflow
- `get_automation_email` — Get email details from workflow

### Reports & Analytics

- `get_account_exports` — Export account data
- `list_unsubscribes` — List all unsubscribes across audiences
- `get_growth_history` — Get audience growth over time
- `get_locations` — Get subscriber geographic data

## 🎯 Example Prompts

Once connected to Claude, you can use natural language:

### Campaign Management
- *"Show me all draft campaigns"*
- *"Create a product announcement email and schedule for Friday 10am"*
- *"What was the open rate on last week's newsletter?"*
- *"Pause the campaign scheduled for tomorrow"*

### Contact Management
- *"Add john@example.com to the VIP list with a 'customer' tag"*
- *"Find all contacts with 'webinar' in their tags"*
- *"Update Sarah's email address to sarah.new@example.com"*
- *"Show me contacts who joined this month"*

### List Building
- *"Create a new audience called 'Product Launch 2024'"*
- *"Import contacts from leads.csv into the newsletter list"*
- *"Show me all unsubscribes from the last campaign"*

### Analytics
- *"Compare open rates between my last 3 campaigns"*
- *"Which links got the most clicks in yesterday's email?"*
- *"Show me subscribers by location"*
- *"What's the growth trend for my main list?"*

### Automation
- *"List all active automations"*
- *"Pause the welcome series for new subscribers"*
- *"Show me emails in the abandoned cart workflow"*

## 🛠️ Development

### Prerequisites
- Node.js 18+
- npm or yarn
- Mailchimp account with API access

### Setup

```bash
git clone https://github.com/YOUR_USERNAME/mailchimp-mcp.git
cd mailchimp-mcp
npm install
cp .env.example .env
# Edit .env with your Mailchimp API key
npm run build
npm start
```

### Project Structure

```
mailchimp-mcp/
├── src/
│   ├── index.ts          # Main MCP server
│   ├── tools/            # Tool implementations
│   │   ├── campaigns.ts
│   │   ├── contacts.ts
│   │   ├── audiences.ts
│   │   ├── templates.ts
│   │   └── reports.ts
│   ├── api/              # Mailchimp API client
│   │   ├── client.ts
│   │   └── auth.ts
│   └── types/            # TypeScript types
├── dist/                 # Compiled JavaScript
├── tests/                # Unit tests
├── package.json
├── tsconfig.json
└── README.md
```

### Testing

```bash
npm test                  # Run all tests
npm run test:watch        # Watch mode
npm run test:coverage     # Coverage report
```

### Building

```bash
npm run build            # Compile TypeScript
npm run build:watch      # Watch mode
```

## 🐛 Troubleshooting

### "Authentication failed"
- Verify your API key is correct (should include datacenter like `-us19`)
- Check that your API key hasn't been revoked in Mailchimp settings
- Ensure you copied the entire key including username prefix

### "Rate limit exceeded"
- Mailchimp has rate limits (typically 10 requests/second)
- The MCP server automatically handles retries
- For bulk operations, reduce concurrency

### "Tools not appearing in Claude"
- Restart Claude Desktop after updating config
- Check that the path in `claude_desktop_config.json` is absolute
- Verify the build completed successfully (`dist/index.js` exists)

### "Audience not found"
- Audience IDs are case-sensitive
- Use `list_audiences` to get the correct ID
- Some operations require admin-level API keys

## 📖 Resources

- [Mailchimp API Documentation](https://mailchimp.com/developer/)
- [Mailchimp Marketing API](https://mailchimp.com/developer/marketing/api/)
- [MCP Protocol Specification](https://modelcontextprotocol.io/)
- [Claude Desktop Documentation](https://claude.ai/desktop)

## 🤝 Contributing

Contributions are welcome! Please:

1. Fork the repo
2. Create a feature branch (`git checkout -b feature/amazing-tool`)
3. Commit your changes (`git commit -m 'Add amazing tool'`)
4. Push to the branch (`git push origin feature/amazing-tool`)
5. Open a Pull Request

## 📄 License

MIT License - see [LICENSE](LICENSE) for details

## 🙏 Credits

Built by [MCPEngine](https://mcpengage.com) — AI infrastructure for business software.

Want more MCP servers? Check out our [full catalog](https://mcpengage.com) covering 30+ business platforms.

---

**Questions?** Open an issue or join our [Discord community](https://discord.gg/mcpengine).
