From 2996871356aea814451218f03f63f28da04231cd Mon Sep 17 00:00:00 2001 From: Jake Shore Date: Mon, 2 Feb 2026 06:58:21 -0500 Subject: [PATCH] Customize: Platform-specific README, tools, and docs --- .env.example | 7 ++- README.md | 130 +++++++++++++++++++++++++++++++++++---------------- package.json | 2 +- 3 files changed, 95 insertions(+), 44 deletions(-) diff --git a/.env.example b/.env.example index 7025aa2..b405ae2 100644 --- a/.env.example +++ b/.env.example @@ -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 diff --git a/README.md b/README.md index ed9953d..b8bc2b9 100644 --- a/README.md +++ b/README.md @@ -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). diff --git a/package.json b/package.json index ba86cfa..a6270b0 100644 --- a/package.json +++ b/package.json @@ -4,7 +4,7 @@ "description": "MCP server for Mailchimp API - 2026 Complete Version", "type": "module", "main": "dist/index.js", - "author": "MCPEngine ", + "author": "MCPEngage ", "license": "MIT", "repository": { "type": "git",