clawdbot-workspace/mcp-github-repos/mailchimp-mcp/README.md

🚀 Don't want to self-host? Join the waitlist for our fully managed solution →

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:

   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
   • 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

   {
     "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

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

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

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

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

Building

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
• Mailchimp Marketing API
• MCP Protocol Specification
• Claude Desktop Documentation

🤝 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 for details

🙏 Credits

Built by MCPEngine — AI infrastructure for business software.

Want more MCP servers? Check out our full catalog covering 30+ business platforms.

---

Questions? Open an issue or join our Discord community.