diff --git a/servers/mailchimp/README.md b/servers/mailchimp/README.md new file mode 100644 index 0000000..90a5e1f --- /dev/null +++ b/servers/mailchimp/README.md @@ -0,0 +1,938 @@ +# 📧 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: "

Welcome!

Check out our new products...

" + } +}); + +// 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** diff --git a/servers/mailchimp/src/clients/mailchimp.ts b/servers/mailchimp/src/clients/mailchimp.ts index 8301ab7..ef8c8ea 100644 --- a/servers/mailchimp/src/clients/mailchimp.ts +++ b/servers/mailchimp/src/clients/mailchimp.ts @@ -50,13 +50,17 @@ export class MailchimpClient { } // Prepare headers - Mailchimp accepts Basic auth with "anystring" as username - const headers: HeadersInit = { + const headers: Record = { 'Content-Type': 'application/json', 'Authorization': `Basic ${Buffer.from(`anystring:${this.apiKey}`).toString('base64')}`, 'User-Agent': 'Mailchimp-MCP-Server/1.0' }; - const options: RequestInit = { + const options: { + method: string; + headers: Record; + body?: string; + } = { method, headers }; diff --git a/servers/mailchimp/src/ui/react-app/audience-grid/index.tsx b/servers/mailchimp/src/ui/react-app/audience-grid/app.tsx similarity index 100% rename from servers/mailchimp/src/ui/react-app/audience-grid/index.tsx rename to servers/mailchimp/src/ui/react-app/audience-grid/app.tsx diff --git a/servers/mailchimp/src/ui/react-app/audience-grid/index.html b/servers/mailchimp/src/ui/react-app/audience-grid/index.html new file mode 100644 index 0000000..197eec6 --- /dev/null +++ b/servers/mailchimp/src/ui/react-app/audience-grid/index.html @@ -0,0 +1,12 @@ + + + + + + Audience Grid + + +
+ + + diff --git a/servers/mailchimp/src/ui/react-app/campaign-dashboard/index.tsx b/servers/mailchimp/src/ui/react-app/campaign-dashboard/app.tsx similarity index 100% rename from servers/mailchimp/src/ui/react-app/campaign-dashboard/index.tsx rename to servers/mailchimp/src/ui/react-app/campaign-dashboard/app.tsx diff --git a/servers/mailchimp/src/ui/react-app/campaign-dashboard/index.html b/servers/mailchimp/src/ui/react-app/campaign-dashboard/index.html new file mode 100644 index 0000000..2088c65 --- /dev/null +++ b/servers/mailchimp/src/ui/react-app/campaign-dashboard/index.html @@ -0,0 +1,12 @@ + + + + + + Campaign Dashboard + + +
+ + +