331 lines
11 KiB
Markdown
331 lines
11 KiB
Markdown
> **🚀 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
|
|
|
|
[](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).
|