jake/mailchimp-mcp-2026-complete
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Customize: Platform-specific README, tools, and docs

Browse Source
This commit is contained in:
Jake Shore 2026-02-02 06:58:21 -05:00
parent 4a69b21dbd
commit 2996871356
3 changed files with 95 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
.env.example
View File

@ -1,2 +1,5 @@
# Mailchimp API Credentials
MAILCHIMP_API_KEY=your-api-key-here
# Mailchimp API Key
# Get from: Profile → Extras → API Keys → Create A Key
# Format: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-us1 (must include data center suffix)
MAILCHIMP_API_KEY=your-api-key-datacenter

130
README.md
View File

@ -8,30 +8,42 @@
## 💡 What This Unlocks
**This MCP server gives AI direct access to your entire Mailchimp workspace.** Instead of clicking through interfaces, you just *tell* it what you need.
**This MCP server gives AI direct access to your Mailchimp email marketing platform.** Instead of manually building campaigns, managing lists, or segmenting audiences, just *tell* AI what you need.
### 🎯 Mailchimp-Native Power Moves
### 📧 Email Marketing Power Moves
The AI can directly control your Mailchimp account with natural language:
The AI can run your entire email marketing operation with natural language:
- **Smart automation** — Complex workflows in plain English
- **Data intelligence** — Query, analyze, and export your Mailchimp data
- **Rapid operations** — Bulk actions that would take hours manually
- **Cross-platform integration** — Combine Mailchimp with other tools seamlessly
| Use Case | What AI Does | Tools Used |
|----------|--------------|------------|
| **"Create a product launch campaign: segment list by purchase history, use template #5, schedule for Friday 10am"** | Creates campaign with targeting rules, applies template, sets send time | `create_campaign`, `list_lists`, `list_templates` |
| **"Show me all campaigns sent in Q4 with open rates below 15%"** | Filters campaigns by date and analyzes performance metrics | `list_campaigns`, `get_campaign` |
| **"Add 500 new subscribers from CSV with tags 'webinar-attendees' and 'tech-industry'"** | Batch imports subscribers with custom tags and merge fields | `add_subscriber` (bulk), `list_lists` |
| **"Generate engagement report: top campaigns, list growth, subscriber churn by segment"** | Aggregates campaign stats, list metrics, and subscriber activity | `list_campaigns`, `list_lists`, `get_subscriber` |
| **"Clone last month's newsletter, update subject line to mention new product, send test to team"** | Duplicates campaign, modifies settings, sends test before scheduling | `get_campaign`, `create_campaign`, `send_campaign` |
### 🔗 The Real Power: Combining Tools
### 🔗 The Real Power: Marketing Automation
AI can chain multiple Mailchimp operations together:
AI chains Mailchimp operations together:
- Query data → Filter results → Generate reports
- Search records → Update fields → Notify team
- Analyze metrics → Create tasks → Schedule follow-ups
- **Audience intelligence** → Analyze subscriber behavior → Segment by engagement → Create targeted campaigns
- **Campaign optimization** → Review past performance → Identify winning templates → Replicate for new sends
- **List health** → Monitor subscriber growth → Flag inactive segments → Re-engagement campaigns
## 📦 What's Inside
**85 API tools** covering the entire Mailchimp platform (Email Marketing).
**8 email marketing tools** covering campaigns, audiences, subscribers, and templates:
All with proper error handling, automatic authentication, and TypeScript types.
1. **`list_campaigns`** — List and filter campaigns by status (sent, scheduled, draft) or type (regular, A/B test)
2. **`get_campaign`** — Get campaign details including content, settings, and performance metrics
3. **`create_campaign`** — Build new campaigns with subject lines, sender info, and audience targeting
4. **`send_campaign`** — Send campaigns immediately (must be fully configured and ready)
5. **`list_lists`** — View all audiences with member counts, growth stats, and settings
6. **`add_subscriber`** — Add new subscribers with email, merge fields (first/last name), tags, and status
7. **`get_subscriber`** — Lookup subscriber by email to see tags, stats, and activity history
8. **`list_templates`** — Browse saved templates (user-created, base layouts, or gallery designs)
All with automatic data center routing, proper error handling, and TypeScript types.
## 🚀 Quick Start
@ -45,7 +57,12 @@ All with proper error handling, automatic authentication, and TypeScript types.
npm run build
```
2. **Get your Mailchimp API credentials** (see Authentication section below)
2. **Get your Mailchimp API key:**
- Log in to Mailchimp
- Go to **Profile → Extras → API Keys**
- Click **Create A Key** and copy it
- Format: `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-us1` (key-datacenter)
- Required permissions: Campaigns, Audiences (read/write)
3. **Configure Claude Desktop:**
@ -58,9 +75,9 @@ All with proper error handling, automatic authentication, and TypeScript types.
"mcpServers": {
"mailchimp": {
"command": "node",
"args": ["/ABSOLUTE/PATH/TO/mailchimp-mcp/dist/index.js"],
"args": ["/ABSOLUTE/PATH/TO/mailchimp-mcp-2026-complete/dist/index.js"],
"env": {
"MAILCHIMP_API_KEY": "your-api-key-here"
"MAILCHIMP_API_KEY": "your-key-datacenter"
}
}
}
@ -74,7 +91,7 @@ All with proper error handling, automatic authentication, and TypeScript types.
[![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/template/mailchimp-mcp)
1. Click the button above
2. Set your Mailchimp API credentials in Railway dashboard
2. Set your Mailchimp API key in Railway dashboard
3. Use the Railway URL as your MCP server endpoint
### Option 3: Docker
@ -82,32 +99,50 @@ All with proper error handling, automatic authentication, and TypeScript types.
```bash
docker build -t mailchimp-mcp .
docker run -p 3000:3000 \
-e MAILCHIMP_API_KEY=your-key \
-e MAILCHIMP_API_KEY=your-key-datacenter \
mailchimp-mcp
```
## 🔐 Authentication
See the official [Mailchimp API documentation](https://docs.mailchimp.com) for authentication details.
Mailchimp uses API key authentication (no OAuth required):
The MCP server handles token refresh automatically.
1. **Get your key**: Mailchimp Profile → Extras → API Keys
2. **Format**: Key includes data center suffix (e.g., `-us1`, `-us19`)
3. **Automatic routing**: MCP server extracts data center from key and routes requests correctly
📚 **Official docs**: [Mailchimp API Authentication](https://mailchimp.com/developer/marketing/guides/quick-start/#generate-your-api-key)
## 🎯 Example Prompts
Once connected to Claude, you can use natural language. Examples:
Once connected to Claude, use natural language:
- *"Show me recent activity in Mailchimp"*
- *"Create a new record with these details..."*
- *"Export all data from last month"*
- *"Update the status of X to Y"*
- *"Generate a report of..."*
**Campaign Management:**
- *"List all campaigns sent in the last 30 days"*
- *"Get full details on campaign 'abc123' including click-through rates"*
- *"Create a regular campaign for list '9876' with subject 'New Product Launch' from 'sales@company.com'"*
- *"Send campaign 'xyz789' immediately"*
**Audience Building:**
- *"Show me all my audiences with subscriber counts"*
- *"Add subscriber jane@example.com to list '9876' with status 'subscribed' and tag 'vip-customer'"*
- *"Get subscriber info for john@example.com from list '9876'"*
**Template Selection:**
- *"List all user-created email templates"*
- *"Show me gallery templates for product announcements"*
**Advanced Workflows:**
- *"Find campaigns with 'newsletter' in the title, show open rates"*
- *"Add 5 subscribers to my main list with tags based on signup source"*
- *"Generate report: campaigns sent this month, total opens, clicks, unsubscribes"*
## 🛠️ Development
### Prerequisites
- Node.js 18+
- npm or yarn
- Mailchimp account with API access
- Mailchimp account with API key
### Setup
@ -116,7 +151,7 @@ git clone https://github.com/BusyBee3333/Mailchimp-MCP-2026-Complete.git
cd mailchimp-mcp-2026-complete
npm install
cp .env.example .env
# Edit .env with your Mailchimp credentials
# Edit .env with your Mailchimp API key
npm run build
npm start
```
@ -131,19 +166,32 @@ npm run test:coverage # Coverage report
## 🐛 Troubleshooting
### "Authentication failed"
- Verify your API credentials are correct
- Check that your API key hasn't been revoked
- Ensure you have the necessary permissions
### "Mailchimp API error: 401 Unauthorized"
- Verify your API key is correct (copy-paste from Mailchimp)
- Check that the key includes the data center suffix (e.g., `-us1`)
- Ensure your API key hasn't been deleted in Mailchimp settings
- Confirm your account is active and in good standing
### "Mailchimp API error: 404 Resource Not Found"
- Campaign/List IDs must be exact matches (case-sensitive)
- Use `list_campaigns` or `list_lists` to get correct IDs
- Some resources may have been archived or deleted
### "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)
- Verify build completed: `ls dist/index.js`
- Check Claude logs: `tail -f ~/Library/Logs/Claude/mcp*.log`
### "Rate limit exceeded"
- Mailchimp limits API calls per key (varies by plan)
- Batch operations when possible (e.g., bulk subscriber imports)
- Check your API usage in Mailchimp dashboard
## 📖 Resources
- [Mailchimp API Documentation](https://docs.mailchimp.com)
- [Mailchimp Marketing API Reference](https://mailchimp.com/developer/marketing/api/)
- [Mailchimp API Quick Start](https://mailchimp.com/developer/marketing/guides/quick-start/)
- [MCP Protocol Specification](https://modelcontextprotocol.io/)
- [Claude Desktop Documentation](https://claude.ai/desktop)
@ -152,9 +200,9 @@ npm run test:coverage # Coverage report
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`)
2. Create a feature branch (`git checkout -b feature/automation-workflows`)
3. Commit your changes (`git commit -m 'Add automation support'`)
4. Push to the branch (`git push origin feature/automation-workflows`)
5. Open a Pull Request
## 📄 License
@ -163,10 +211,10 @@ MIT License - see [LICENSE](LICENSE) for details
## 🙏 Credits
Built by [MCPEngine](https://mcpengage.com) — AI infrastructure for business software.
Built by [MCPEngage](https://mcpengage.com) — AI infrastructure for business software.
Want more MCP servers? Check out our [full catalog](https://mcpengage.com) covering 30+ business platforms.
Want more MCP servers? Check our [catalog](https://mcpengine.pages.dev) covering 30+ business platforms.
---
**Questions?** Open an issue or join our [Discord community](https://discord.gg/mcpengine).
**Questions?** Open an issue or join our [Discord community](https://discord.gg/mcpengage).

2
package.json
View File

@ -4,7 +4,7 @@
"description": "MCP server for Mailchimp API - 2026 Complete Version",
"type": "module",
"main": "dist/index.js",
"author": "MCPEngine <hello@mcpengage.com>",
"author": "MCPEngage <hello@mcpengage.com>",
"license": "MIT",
"repository": {
"type": "git",