# 📧 Mailchimp MCP Server

A comprehensive Model Context Protocol (MCP) server providing complete access to the Mailchimp Marketing API v3, with **104 tools** and **15 interactive React apps**.

[![MCP Version](https://img.shields.io/badge/MCP-1.0.4-blue)](https://modelcontextprotocol.io)
[![Mailchimp API](https://img.shields.io/badge/Mailchimp%20API-v3-yellow)](https://mailchimp.com/developer/)
[![Tools](https://img.shields.io/badge/Tools-104-green)](#tool-reference)
[![Apps](https://img.shields.io/badge/Apps-15-purple)](#react-apps-showcase)

## 🚀 Features

- **104 MCP Tools** covering the complete Mailchimp Marketing API
- **15 Interactive React Apps** for visual campaign management, audience analytics, and e-commerce tracking
- **Full Campaign Lifecycle** — create, test, schedule, send, and analyze campaigns
- **Audience Management** — lists, members, segments, tags, and interest groups
- **E-commerce Integration** — stores, products, orders, carts, customers, and promo codes
- **Marketing Automation** — automated workflows and triggered emails
- **Landing Pages** — create and manage standalone landing pages
- **Advanced Reporting** — campaign performance, click tracking, and audience growth
- **Template Management** — reusable email templates
- **Search & Discovery** — search across campaigns, members, and tags

---

## 📦 Installation

```bash
npm install @mcpengine/mailchimp-mcp-server
```

Or install from source:

```bash
git clone https://github.com/BusyBee3333/mcpengine.git
cd mcpengine/servers/mailchimp
npm install
npm run build
```

---

## 🔑 Authentication

Set your Mailchimp API key as an environment variable:

```bash
export MAILCHIMP_API_KEY="your_key_here-us19"
```

**API Key Format:** `xxxxxxxxxxxxx-datacenter` (e.g., `abc123-us19`)

**Get your API key:**
1. Log in to Mailchimp
2. Go to Account → Extras → API Keys
3. Generate a new API key
4. Note the datacenter suffix (e.g., `us19`)

---

## ⚙️ Configuration

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "mailchimp": {
      "command": "node",
      "args": ["/path/to/mailchimp-mcp-server/dist/index.js"],
      "env": {
        "MAILCHIMP_API_KEY": "your_key_here-us19"
      }
    }
  }
}
```

### Cline / Roo Cline

Add to your MCP settings:

```json
{
  "mailchimp": {
    "command": "mailchimp-mcp",
    "env": {
      "MAILCHIMP_API_KEY": "your_key_here-us19"
    }
  }
}
```

---

## 🎨 React Apps Showcase

The Mailchimp MCP server includes **15 interactive React apps** for visual management and analytics.

### Campaign Management Apps

#### 📊 Campaign Dashboard (`campaign-dashboard`)
**Real-time campaign overview with performance metrics**

Features:
- Total campaigns count
- Campaigns sent today
- Average open rate across all campaigns
- Average click rate across all campaigns
- Recent campaigns table with status, emails sent, and engagement metrics
- Auto-refresh capability

Tools used: `mailchimp_campaigns_list`, `mailchimp_reports_list`

---

#### 📧 Campaign Detail (`campaign-detail`)
**Detailed view of a single campaign**

Features:
- Campaign metadata (title, subject line, preview text)
- Recipient targeting (list, segment)
- Delivery settings (from name, reply-to)
- Tracking options (opens, clicks, e-commerce)
- Campaign content preview
- Send checklist validation
- Quick actions: send, schedule, test, replicate, delete

Tools used: `mailchimp_campaigns_get`, `mailchimp_campaigns_get_content`, `mailchimp_campaigns_get_send_checklist`, `mailchimp_campaigns_send`, `mailchimp_campaigns_schedule`, `mailchimp_campaigns_test`

---

#### 🏗️ Campaign Builder (`campaign-builder`)
**Visual campaign creation wizard**

Features:
- Step-by-step campaign setup
- Audience selection with segment targeting
- Subject line and preview text editor
- From name and reply-to configuration
- Template selection or HTML editor
- Tracking settings (opens, clicks, social, e-commerce)
- Preview and send test
- Schedule or send immediately

Tools used: `mailchimp_campaigns_create`, `mailchimp_campaigns_set_content`, `mailchimp_lists_list`, `mailchimp_templates_list`, `mailchimp_campaigns_test`, `mailchimp_campaigns_send`

---

### Audience Management Apps

#### 👥 Audience Dashboard (`audience-dashboard`)
**Overview of all lists/audiences with growth metrics**

Features:
- Total subscribers across all lists
- New subscribers today
- Average engagement rate
- Unsubscribe rate tracking
- List comparison table (size, growth, engagement)
- Member status breakdown (subscribed, unsubscribed, cleaned, pending)

Tools used: `mailchimp_lists_list`, `mailchimp_lists_get`, `mailchimp_lists_growth_history`

---

#### 📋 Audience Grid (`audience-grid`)
**Interactive member directory with filtering**

Features:
- Paginated member list
- Real-time search by email or name
- Filter by status (subscribed, unsubscribed, pending, cleaned)
- Filter by tags
- Sort by join date, engagement, last changed
- Member quick actions (view detail, add tags, update status)
- Bulk operations
- Export member list

Tools used: `mailchimp_lists_members_list`, `mailchimp_lists_members_search`, `mailchimp_members_tags_add`, `mailchimp_members_update`

---

#### 🔍 Member Detail (`member-detail`)
**Comprehensive member profile view**

Features:
- Contact information (email, name, location)
- Subscription status and history
- Tags assigned to member
- Interest groups/preferences
- Campaign activity (opens, clicks)
- E-commerce activity (orders, total spent)
- Member notes
- Timeline of interactions
- Quick actions: update info, add tags, change status, delete

Tools used: `mailchimp_lists_members_get`, `mailchimp_members_tags_list`, `mailchimp_members_activity`, `mailchimp_members_update`, `mailchimp_members_delete`

---

#### 🏷️ Tag Manager (`tag-manager`)
**Organize and manage member tags**

Features:
- All tags across account with usage count
- Search tags by name
- View members tagged with specific tag
- Bulk tag operations (add/remove to multiple members)
- Tag performance insights (engagement rate by tag)
- Create new tags
- Merge duplicate tags
- Delete unused tags

Tools used: `mailchimp_search_tags`, `mailchimp_lists_members_list`, `mailchimp_members_tags_add`, `mailchimp_members_tags_remove`

---

### Automation Apps

#### ⚙️ Automation Dashboard (`automation-dashboard`)
**Overview of all automation workflows**

Features:
- Active automations count
- Total emails sent via automation
- Automation performance metrics
- Workflow list with status, trigger type, and stats
- Recently started/paused automations
- Automation health indicators

Tools used: `mailchimp_automations_list`, `mailchimp_automations_get`

---

#### 🔄 Automation Detail (`automation-detail`)
**Detailed automation workflow viewer**

Features:
- Workflow structure visualization
- Trigger settings
- Email sequence breakdown
- Delay settings between emails
- Recipient criteria
- Performance stats per email
- Workflow actions: pause, start, remove subscriber
- Email preview and edit

Tools used: `mailchimp_automations_get`, `mailchimp_automations_emails_list`, `mailchimp_automations_pause`, `mailchimp_automations_start`, `mailchimp_automations_subscribers_remove`

---

### Reporting & Analytics Apps

#### 📈 Report Dashboard (`report-dashboard`)
**Campaign performance analytics overview**

Features:
- Total campaigns sent (all-time, last 30 days)
- Aggregate engagement metrics
- Top performing campaigns (by opens, clicks, revenue)
- Bottom performing campaigns
- Performance trends over time
- Industry benchmark comparison
- Export reports

Tools used: `mailchimp_reports_list`, `mailchimp_reports_get`

---

#### 📊 Campaign Report (`report-detail`)
**Detailed campaign performance analysis**

Features:
- Delivery metrics (sent, delivered, bounces, opens, clicks)
- Open rate timeline
- Click tracking with URL breakdown
- Geographic distribution of opens
- Device/email client breakdown
- Social performance
- E-commerce revenue attribution
- Top clickers/openers
- Unsubscribe analysis

Tools used: `mailchimp_reports_get`, `mailchimp_reports_click_details`, `mailchimp_reports_locations`, `mailchimp_reports_email_activity`

---

#### 📊 Growth Chart (`growth-chart`)
**Visual audience growth tracking**

Features:
- Subscriber growth timeline
- Net growth (new subscribers - unsubscribes)
- Engagement rate trends
- Cohort analysis
- Forecast projections
- Export chart data

Tools used: `mailchimp_lists_growth_history`, `mailchimp_lists_list`

---

### E-commerce Apps

#### 🛒 E-commerce Dashboard (`ecommerce-dashboard`)
**Mailchimp e-commerce tracking overview**

Features:
- Total revenue attributed to campaigns
- Orders generated from emails
- Average order value
- Top products sold via email
- Customer lifetime value
- Store performance comparison
- Cart abandonment stats
- Promo code usage tracking

Tools used: `mailchimp_ecommerce_stores_list`, `mailchimp_ecommerce_orders_list`, `mailchimp_ecommerce_products_list`, `mailchimp_ecommerce_promo_codes_list`

---

### Landing Pages & Content

#### 🎯 Landing Page Grid (`landing-page-grid`)
**Manage Mailchimp landing pages**

Features:
- All landing pages list
- Filter by published/unpublished status
- Preview thumbnails
- Performance metrics (visits, conversions, conversion rate)
- Quick actions: view, edit, publish, unpublish, delete
- Create new landing page

Tools used: `mailchimp_landing_pages_list`, `mailchimp_landing_pages_get`, `mailchimp_landing_pages_create`, `mailchimp_landing_pages_publish`, `mailchimp_landing_pages_unpublish`, `mailchimp_landing_pages_delete`

---

#### 🎨 Template Gallery (`template-gallery`)
**Email template library**

Features:
- All saved templates
- Filter by type (user, base, gallery)
- Template preview
- Usage statistics
- Quick actions: use in campaign, edit, duplicate, delete
- Create new template from scratch or HTML
- Import template from URL

Tools used: `mailchimp_templates_list`, `mailchimp_templates_get`, `mailchimp_templates_create`, `mailchimp_templates_update`, `mailchimp_templates_delete`

---

### Testing & Optimization

#### 🔬 A/B Test Results (`ab-test-results`)
**A/B test campaign analysis**

Features:
- Test configuration (what was tested: subject, from name, content, send time)
- Variant performance comparison
- Statistical significance calculator
- Winner declaration
- Engagement breakdown per variant
- Recommended next steps
- Export test results

Tools used: `mailchimp_campaigns_get`, `mailchimp_reports_get`

---

#### 🔎 Search Results (`search-results`)
**Universal search across Mailchimp account**

Features:
- Search campaigns by title, subject line
- Search members by email, name
- Search tags
- Filter results by type
- Quick actions from results
- Search history
- Advanced filters

Tools used: `mailchimp_search_campaigns`, `mailchimp_search_members`, `mailchimp_search_tags`

---

## 🛠️ Tool Reference

### 📧 Campaign Tools (15 tools)

| Tool | Description |
|------|-------------|
| `mailchimp_campaigns_list` | List all campaigns with filters (type, status, list, folder) |
| `mailchimp_campaigns_get` | Get details for a specific campaign |
| `mailchimp_campaigns_create` | Create a new campaign (regular, A/B split, RSS, etc.) |
| `mailchimp_campaigns_update` | Update campaign settings, recipients, or tracking |
| `mailchimp_campaigns_delete` | Permanently delete a campaign |
| `mailchimp_campaigns_send` | Send a campaign immediately |
| `mailchimp_campaigns_schedule` | Schedule campaign for future send (supports Timewarp) |
| `mailchimp_campaigns_unschedule` | Unschedule a scheduled campaign |
| `mailchimp_campaigns_pause` | Pause an RSS campaign |
| `mailchimp_campaigns_resume` | Resume a paused RSS campaign |
| `mailchimp_campaigns_replicate` | Duplicate a campaign |
| `mailchimp_campaigns_test` | Send test email to up to 5 addresses |
| `mailchimp_campaigns_get_content` | Get HTML and plain-text content |
| `mailchimp_campaigns_set_content` | Set content (HTML, template, or URL import) |
| `mailchimp_campaigns_get_send_checklist` | Review pre-send checklist |

---

### 👥 List/Audience Tools (14 tools)

| Tool | Description |
|------|-------------|
| `mailchimp_lists_list` | List all audiences/lists |
| `mailchimp_lists_get` | Get audience details and stats |
| `mailchimp_lists_create` | Create a new audience |
| `mailchimp_lists_update` | Update audience settings |
| `mailchimp_lists_delete` | Delete an audience |
| `mailchimp_lists_batch_subscribe` | Add/update multiple members in one call |
| `mailchimp_lists_segments_list` | List segments in an audience |
| `mailchimp_lists_segments_create` | Create a new segment |
| `mailchimp_lists_segments_update` | Update segment conditions |
| `mailchimp_lists_segments_delete` | Delete a segment |
| `mailchimp_lists_interest_categories_list` | List interest categories (groups) |
| `mailchimp_lists_interest_categories_create` | Create interest category |
| `mailchimp_lists_interests_list` | List interests within a category |
| `mailchimp_lists_growth_history` | Get audience growth history |

---

### 🙋 Member Tools (12 tools)

| Tool | Description |
|------|-------------|
| `mailchimp_lists_members_list` | List members in an audience |
| `mailchimp_lists_members_get` | Get member details |
| `mailchimp_lists_members_add` | Add a new member to an audience |
| `mailchimp_lists_members_update` | Update member information |
| `mailchimp_lists_members_delete` | Permanently delete a member |
| `mailchimp_lists_members_archive` | Archive (soft delete) a member |
| `mailchimp_lists_members_search` | Search members by query |
| `mailchimp_members_tags_list` | List tags for a member |
| `mailchimp_members_tags_add` | Add tags to a member |
| `mailchimp_members_tags_remove` | Remove tags from a member |
| `mailchimp_members_activity` | Get member activity (opens, clicks) |
| `mailchimp_members_notes` | Get notes for a member |

---

### 📄 Template Tools (6 tools)

| Tool | Description |
|------|-------------|
| `mailchimp_templates_list` | List all email templates |
| `mailchimp_templates_get` | Get template details and HTML |
| `mailchimp_templates_create` | Create a new template |
| `mailchimp_templates_update` | Update template content |
| `mailchimp_templates_delete` | Delete a template |
| `mailchimp_templates_get_default_content` | Get default content for a template |

---

### ⚙️ Automation Tools (10 tools)

| Tool | Description |
|------|-------------|
| `mailchimp_automations_list` | List all automation workflows |
| `mailchimp_automations_get` | Get automation details |
| `mailchimp_automations_pause` | Pause an automation |
| `mailchimp_automations_start` | Start a paused automation |
| `mailchimp_automations_emails_list` | List emails in an automation |
| `mailchimp_automations_emails_get` | Get automation email details |
| `mailchimp_automations_emails_pause` | Pause a specific automation email |
| `mailchimp_automations_emails_start` | Start a paused automation email |
| `mailchimp_automations_subscribers_add` | Add subscriber to automation |
| `mailchimp_automations_subscribers_remove` | Remove subscriber from automation |

---

### 📊 Report Tools (8 tools)

| Tool | Description |
|------|-------------|
| `mailchimp_reports_list` | List campaign reports |
| `mailchimp_reports_get` | Get detailed campaign report |
| `mailchimp_reports_email_activity` | Get email activity for specific recipients |
| `mailchimp_reports_locations` | Get geographic data (opens by location) |
| `mailchimp_reports_sent_to` | List recipients a campaign was sent to |
| `mailchimp_reports_click_details` | Get click tracking details |
| `mailchimp_reports_opened` | List recipients who opened |
| `mailchimp_reports_unsubscribed` | List recipients who unsubscribed |

---

### 🎯 Landing Page Tools (8 tools)

| Tool | Description |
|------|-------------|
| `mailchimp_landing_pages_list` | List all landing pages |
| `mailchimp_landing_pages_get` | Get landing page details |
| `mailchimp_landing_pages_create` | Create a new landing page |
| `mailchimp_landing_pages_update` | Update landing page content |
| `mailchimp_landing_pages_delete` | Delete a landing page |
| `mailchimp_landing_pages_publish` | Publish a landing page |
| `mailchimp_landing_pages_unpublish` | Unpublish a landing page |
| `mailchimp_landing_pages_content` | Get/set landing page content |

---

### 🛒 E-commerce Tools (28 tools)

| Tool | Description |
|------|-------------|
| `mailchimp_ecommerce_stores_list` | List connected stores |
| `mailchimp_ecommerce_stores_get` | Get store details |
| `mailchimp_ecommerce_stores_create` | Connect a new store |
| `mailchimp_ecommerce_stores_update` | Update store info |
| `mailchimp_ecommerce_stores_delete` | Disconnect a store |
| `mailchimp_ecommerce_products_list` | List products in a store |
| `mailchimp_ecommerce_products_get` | Get product details |
| `mailchimp_ecommerce_products_create` | Add a new product |
| `mailchimp_ecommerce_products_update` | Update product info |
| `mailchimp_ecommerce_products_delete` | Remove a product |
| `mailchimp_ecommerce_variants_list` | List product variants |
| `mailchimp_ecommerce_variants_create` | Add product variant |
| `mailchimp_ecommerce_orders_list` | List orders from a store |
| `mailchimp_ecommerce_orders_get` | Get order details |
| `mailchimp_ecommerce_orders_create` | Record a new order |
| `mailchimp_ecommerce_orders_update` | Update order info |
| `mailchimp_ecommerce_orders_delete` | Delete an order |
| `mailchimp_ecommerce_carts_list` | List abandoned carts |
| `mailchimp_ecommerce_carts_get` | Get cart details |
| `mailchimp_ecommerce_carts_create` | Create a cart record |
| `mailchimp_ecommerce_carts_update` | Update cart |
| `mailchimp_ecommerce_carts_delete` | Delete cart |
| `mailchimp_ecommerce_customers_list` | List customers |
| `mailchimp_ecommerce_customers_get` | Get customer details |
| `mailchimp_ecommerce_customers_create` | Add customer |
| `mailchimp_ecommerce_promo_codes_list` | List promo codes |
| `mailchimp_ecommerce_promo_codes_get` | Get promo code details |
| `mailchimp_ecommerce_promo_codes_create` | Create promo code |

---

### 🔍 Search & Discovery Tools (3 tools)

| Tool | Description |
|------|-------------|
| `mailchimp_search_campaigns` | Search campaigns by keyword |
| `mailchimp_search_members` | Search members across all lists |
| `mailchimp_search_tags` | Search tags across account |

---

## 💡 Usage Examples

### Example 1: Create and Send a Campaign

```typescript
// 1. Create campaign
const campaign = await use_mcp_tool({
  server_name: "mailchimp",
  tool_name: "mailchimp_campaigns_create",
  arguments: {
    type: "regular",
    recipients: {
      list_id: "abc123"
    },
    settings: {
      subject_line: "🎉 New Product Launch!",
      preview_text: "Check out our latest products",
      title: "Product Launch Campaign - Q1 2024",
      from_name: "MyBrand",
      reply_to: "hello@mybrand.com"
    }
  }
});

// 2. Set content
await use_mcp_tool({
  server_name: "mailchimp",
  tool_name: "mailchimp_campaigns_set_content",
  arguments: {
    campaign_id: campaign.id,
    html: "<h1>Welcome!</h1><p>Check out our new products...</p>"
  }
});

// 3. Send test
await use_mcp_tool({
  server_name: "mailchimp",
  tool_name: "mailchimp_campaigns_test",
  arguments: {
    campaign_id: campaign.id,
    test_emails: ["test@mybrand.com"],
    send_type: "html"
  }
});

// 4. Send campaign
await use_mcp_tool({
  server_name: "mailchimp",
  tool_name: "mailchimp_campaigns_send",
  arguments: {
    campaign_id: campaign.id
  }
});
```

---

### Example 2: Add Member with Tags

```typescript
// Add member to list
await use_mcp_tool({
  server_name: "mailchimp",
  tool_name: "mailchimp_lists_members_add",
  arguments: {
    list_id: "abc123",
    email_address: "customer@example.com",
    status: "subscribed",
    merge_fields: {
      FNAME: "Jane",
      LNAME: "Doe"
    }
  }
});

// Add tags
await use_mcp_tool({
  server_name: "mailchimp",
  tool_name: "mailchimp_members_tags_add",
  arguments: {
    list_id: "abc123",
    email_address: "customer@example.com",
    tags: [
      { name: "VIP", status: "active" },
      { name: "Product-Launch-2024", status: "active" }
    ]
  }
});
```

---

### Example 3: Create Automated Welcome Series

```typescript
// Create automation
const automation = await use_mcp_tool({
  server_name: "mailchimp",
  tool_name: "mailchimp_automations_create",
  arguments: {
    recipients: {
      list_id: "abc123"
    },
    trigger_settings: {
      workflow_type: "emailAdded"
    },
    settings: {
      title: "Welcome Series",
      from_name: "MyBrand",
      reply_to: "hello@mybrand.com"
    }
  }
});

// Automation emails are managed via the API or UI
// Start the automation
await use_mcp_tool({
  server_name: "mailchimp",
  tool_name: "mailchimp_automations_start",
  arguments: {
    workflow_id: automation.id
  }
});
```

---

### Example 4: Track E-commerce Order

```typescript
// Record an order
await use_mcp_tool({
  server_name: "mailchimp",
  tool_name: "mailchimp_ecommerce_orders_create",
  arguments: {
    store_id: "mystore",
    order: {
      id: "order_12345",
      customer: {
        id: "customer_abc",
        email_address: "customer@example.com",
        opt_in_status: true
      },
      currency_code: "USD",
      order_total: 99.99,
      lines: [
        {
          id: "line_1",
          product_id: "prod_123",
          product_variant_id: "var_456",
          quantity: 2,
          price: 49.99
        }
      ]
    }
  }
});
```

---

### Example 5: Analyze Campaign Performance

```typescript
// Get campaign report
const report = await use_mcp_tool({
  server_name: "mailchimp",
  tool_name: "mailchimp_reports_get",
  arguments: {
    campaign_id: "campaign_xyz"
  }
});

console.log(`Open Rate: ${(report.opens.open_rate * 100).toFixed(2)}%`);
console.log(`Click Rate: ${(report.clicks.click_rate * 100).toFixed(2)}%`);

// Get click details
const clicks = await use_mcp_tool({
  server_name: "mailchimp",
  tool_name: "mailchimp_reports_click_details",
  arguments: {
    campaign_id: "campaign_xyz"
  }
});

// Most clicked link
const topLink = clicks.urls_clicked[0];
console.log(`Most clicked: ${topLink.url} (${topLink.total_clicks} clicks)`);
```

---

## 🏗️ Architecture

```
mailchimp-mcp-server/
├── src/
│   ├── index.ts                 # MCP server entry point
│   ├── clients/
│   │   └── mailchimp.ts         # Mailchimp API client
│   ├── types/
│   │   └── index.ts             # TypeScript type definitions
│   ├── tools/                   # Tool implementations (104 tools)
│   │   ├── campaigns-tools.ts   # 15 campaign tools
│   │   ├── lists-tools.ts       # 14 list/audience tools
│   │   ├── members-tools.ts     # 12 member tools
│   │   ├── templates-tools.ts   # 6 template tools
│   │   ├── automations-tools.ts # 10 automation tools
│   │   ├── reports-tools.ts     # 8 report tools
│   │   ├── landing-pages-tools.ts # 8 landing page tools
│   │   ├── ecommerce-tools.ts   # 28 e-commerce tools
│   │   ├── tags-tools.ts        # 1 tag tool
│   │   └── search-tools.ts      # 2 search tools
│   └── ui/
│       └── react-app/           # React MCP apps (15 apps)
│           ├── campaign-dashboard/
│           ├── campaign-detail/
│           ├── campaign-builder/
│           ├── audience-dashboard/
│           ├── audience-grid/
│           ├── member-detail/
│           ├── tag-manager/
│           ├── automation-dashboard/
│           ├── automation-detail/
│           ├── report-dashboard/
│           ├── report-detail/
│           ├── growth-chart/
│           ├── ecommerce-dashboard/
│           ├── landing-page-grid/
│           ├── template-gallery/
│           ├── ab-test-results/
│           └── search-results/
├── scripts/
│   └── build-apps.js            # React app bundler
├── package.json
├── tsconfig.json
└── README.md
```

---

## 🔧 Development

### Build

```bash
npm run build
```

Compiles TypeScript and bundles all React apps.

### Development Mode

```bash
npm run dev
```

Runs TypeScript in watch mode.

### Type Checking

```bash
npm run typecheck
```

---

## 📚 API Documentation

This MCP server covers the Mailchimp Marketing API v3. For full API documentation:

- [Mailchimp Marketing API Reference](https://mailchimp.com/developer/marketing/api/)
- [Campaign API Docs](https://mailchimp.com/developer/marketing/api/campaigns/)
- [Lists API Docs](https://mailchimp.com/developer/marketing/api/lists/)
- [Automation API Docs](https://mailchimp.com/developer/marketing/api/automation/)
- [E-commerce API Docs](https://mailchimp.com/developer/marketing/api/ecommerce-stores/)

---

## ⚡ Rate Limiting

Mailchimp enforces rate limits on API requests (typically 10 requests/second). This MCP server handles rate limiting automatically with exponential backoff and retry logic.

---

## 🔒 Security Best Practices

1. **Never commit API keys** — use environment variables
2. **Rotate API keys** regularly
3. **Use read-only keys** when possible (Mailchimp doesn't support this yet)
4. **Monitor API usage** in your Mailchimp account
5. **Restrict MCP access** to trusted users/environments

---

## 🐛 Troubleshooting

### "Error: MAILCHIMP_API_KEY environment variable is required"

Set your API key:
```bash
export MAILCHIMP_API_KEY="your_key-us19"
```

### "Invalid API Key"

Check:
- API key format includes datacenter (e.g., `-us19`)
- API key is active in your Mailchimp account
- No extra spaces or quotes in the environment variable

### "Rate Limit Exceeded"

The server will automatically retry with exponential backoff. If persistent:
- Reduce request frequency
- Check Mailchimp account limits
- Consider upgrading Mailchimp plan

### "List Not Found"

Ensure you're using the correct `list_id`. Get list IDs via:
```typescript
await use_mcp_tool({
  server_name: "mailchimp",
  tool_name: "mailchimp_lists_list"
});
```

---

## 📊 Comparison: Mailchimp MCP vs. GoHighLevel MCP

| Metric | Mailchimp MCP | GoHighLevel MCP |
|--------|---------------|-----------------|
| **Tools** | 104 | 474 |
| **React Apps** | 15 | 65 |
| **API Coverage** | Mailchimp Marketing API v3 | GoHighLevel API v2 |
| **Focus** | Email marketing, automation, e-commerce | CRM, marketing automation, sales funnels |
| **Complexity** | Medium | High |
| **Use Case** | Email campaigns, newsletters, e-commerce stores | Agency/SaaS white-label platform |

Both servers provide **comprehensive MCP coverage** of their respective platforms with rich UI apps and complete API tool sets.

---

## 🤝 Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new tools
4. Submit a pull request

---

## 📄 License

MIT License - see LICENSE file for details

---

## 🙏 Acknowledgments

- Built with the [Model Context Protocol SDK](https://modelcontextprotocol.io)
- Powered by [Mailchimp Marketing API v3](https://mailchimp.com/developer/)
- Part of the [MCPEngine](https://github.com/BusyBee3333/mcpengine) project

---

## 📞 Support

- **Issues:** [GitHub Issues](https://github.com/BusyBee3333/mcpengine/issues)
- **Documentation:** [MCPEngine Docs](https://github.com/BusyBee3333/mcpengine)
- **Mailchimp API:** [Mailchimp Developer Docs](https://mailchimp.com/developer/)

---

**Made with ❤️ by the MCPEngine team**