Content
# Mailchimp MCP Server
A Model Context Protocol (MCP) server for integrating Mailchimp with Claude Desktop.
## ⚠️ Security & Privacy Notice
**IMPORTANT:** This MCP server exposes personal data to Claude AI and Claude Desktop:
- Email addresses and member information are sent to Claude AI via tool responses
- Claude Desktop stores conversation history locally on your device
- Use only with accounts containing non-sensitive data
- Enable PII masking (`MAILCHIMP_MASK_PII=true`) to protect personal information
- Review [SECURITY.md](./SECURITY.md) for detailed security information
## Quick Start
> 💡 **New to Mailchimp MCP?** See [INSTALL.md](./INSTALL.md) for detailed installation instructions and troubleshooting.
### 🚀 Installation Options
#### Option 1: macOS Installer App (Recommended for macOS)
Download the DMG file from [GitHub Releases](https://github.com/alien-lifestyles/mailchimp-mcp-alien-lifestyles/releases):
1. Download `MailchimpMCPInstaller.dmg`
2. Open the DMG file
3. Double-click `MailchimpMCPInstaller.app`
4. Follow the installation wizard
5. Enter your Mailchimp API key when prompted
6. Restart Claude Desktop
The installer will:
- ✅ Check prerequisites (Node.js, npm)
- ✅ Install the package globally
- ✅ Launch the setup UI in your browser
- ✅ Automatically configure Claude Desktop
- ✅ Validate that Claude Desktop will auto-start Mailchimp MCP
**Uninstaller:** The DMG also includes `MailchimpMCPUninstaller.app` to completely remove Mailchimp MCP and all associated data.
#### Option 2: Command Line (All Platforms)
**For macOS:**
```bash
curl -fsSL https://raw.githubusercontent.com/alien-lifestyles/mailchimp-mcp-alien-lifestyles/main/install.sh | bash
```
**For All Platforms (using npx):**
```bash
npx -y @alien-lifestyles/mailchimp-mcp mailchimp-mcp-install
```
**Manual Install:**
```bash
npm install -g @alien-lifestyles/mailchimp-mcp && mailchimp-mcp-setup
```
### 📝 Step-by-Step Installation
**Step 1: Install**
```bash
npm install -g @alien-lifestyles/mailchimp-mcp
```
**Step 2: Run Setup**
```bash
mailchimp-mcp-setup
```
Or if installed locally:
```bash
npm run setup
```
**Step 3: Configure**
The setup UI will open in your browser at `http://localhost:3000`. Enter:
- ✅ Your Mailchimp API key (required)
- ✅ Server prefix (auto-detected from API key)
- ⭐ License key (optional - for paid features)
- 🔒 Privacy settings (PII masking recommended)
**Step 4: Restart Claude Desktop**
After saving your configuration, restart Claude Desktop completely for changes to take effect.
**Step 5: Test**
Ask Claude: "Can you run mc_ping?" to verify the connection.
### 🔧 Manual Configuration (Advanced)
If you prefer manual setup, create a `.env` file:
```bash
# Required
MAILCHIMP_API_KEY=your_api_key_here-us9
MAILCHIMP_SERVER_PREFIX=us9
# Optional
MAILCHIMP_LICENSE_KEY=ALIEN-XXXX-XXXX-XXXX
MAILCHIMP_MASK_PII=true
```
Then manually edit Claude Desktop config at:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
Add:
```json
{
"mcpServers": {
"mailchimp-mcp": {
"command": "node",
"args": ["/path/to/@alien-lifestyles/mailchimp-mcp/dist/index.js"],
"cwd": "/path/to/@alien-lifestyles/mailchimp-mcp",
"env": {
"MAILCHIMP_API_KEY": "your_api_key_here-us9",
"MAILCHIMP_SERVER_PREFIX": "us9",
"MAILCHIMP_MASK_PII": "true"
}
}
}
}
```
## Free vs Paid Versions
### Free Version (Default)
- Read-only access to audiences, campaigns, reports
- 5 Marketer prompts
- No write operations
- No license key required
### Paid Version
- Full read/write access
- All prompts (CSM, Marketer, Business Owner)
- Create campaigns, templates, audiences
- File Manager integration
- Requires license key from [alienlifestyles.com](https://alienlifestyles.com)
## Available Tools
### Read Tools
| Tool | Description |
|------|-------------|
| `mc_ping` | Test connection |
| `mc_listAudiences` | List all audiences |
| `mc_getAudience` | Get audience details |
| `mc_listMembers` | List members in audience |
| `mc_getMember` | Get member details |
| `mc_listCampaigns` | List campaigns |
| `mc_getCampaign` | Get campaign details |
| `mc_getCampaignReport` | Get campaign analytics |
| `mc_getAccount` | Get account information |
| `mc_listVerifiedDomains` | List verified domains |
| `mc_getVerifiedDomain` | Get domain auth status |
### Write Tools (Paid Only)
| Tool | Description |
|------|-------------|
| **Campaigns** | |
| `mc_createCampaign` | Create new campaign |
| `mc_updateCampaign` | Update campaign settings |
| `mc_setCampaignContent` | Set campaign content |
| `mc_sendCampaign` | Send campaign |
| `mc_deleteCampaign` | Delete campaign |
| **Templates** | |
| `mc_createTemplate` | Create template with MTL validation |
| `mc_updateTemplate` | Update template |
| `mc_deleteTemplate` | Delete template |
| **Files & Folders** | |
| `mc_uploadFile` | Upload file to File Manager |
| `mc_deleteFile` | Delete file from File Manager |
| `mc_createTemplateFolder` | Create template folder |
| `mc_deleteTemplateFolder` | Delete template folder |
| `mc_createFileFolder` | Create file folder |
| `mc_deleteFileFolder` | Delete file folder |
| **Audiences** | |
| `mc_createAudience` | Create new audience |
| `mc_updateAudience` | Update audience settings |
| `mc_deleteAudience` | Delete audience |
| **Members** | |
| `mc_createMember` | Add member to audience |
| `mc_updateMember` | Update member information |
| `mc_deleteMember` | Delete member from audience |
| **Segments** | |
| `mc_createSegment` | Create segment |
| `mc_updateSegment` | Update segment |
| `mc_deleteSegment` | Delete segment |
| **Tags** | |
| `mc_createTag` | Create tag |
| `mc_addTagToMember` | Add/remove tags from member |
| `mc_deleteTag` | Delete tag |
| **Merge Fields** | |
| `mc_createMergeField` | Create merge field |
| `mc_updateMergeField` | Update merge field |
| `mc_deleteMergeField` | Delete merge field |
| **Domains** | |
| `mc_createVerifiedDomain` | Add domain for verification |
| `mc_deleteVerifiedDomain` | Delete verified domain |
| `mc_sendDomainVerificationEmail` | Send domain verification email |
| **E-commerce Stores** | |
| `mc_deleteStore` | Delete e-commerce store (Note: Mailchimp Stores API is read-only - stores must be deleted via web interface) |
## Example Queries
- "List my Mailchimp audiences"
- "How many subscribers do I have?"
- "Show me my recent campaigns"
- "What's my top performing campaign?"
- "Check my domain authentication status"
See [USE_CASES.md](./USE_CASES.md) for more examples.
## Environment Variables
| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `MAILCHIMP_API_KEY` | Mailchimp API key (with datacenter suffix) | Yes | - |
| `MAILCHIMP_SERVER_PREFIX` | Datacenter prefix (e.g., `us9`) | Yes | `us21` |
| `MAILCHIMP_LICENSE_KEY` | License key for paid version | No | - |
| `MAILCHIMP_READONLY` | Enable read-only mode | No | `true` |
| `MAILCHIMP_MASK_PII` | Mask email addresses and PII | No | `false` |
## Troubleshooting
### API Key Invalid
- Verify API key is correct and active in Mailchimp
- Ensure datacenter prefix matches (e.g., `us9` in key and `MAILCHIMP_SERVER_PREFIX`)
- Use full, unmasked API key including datacenter suffix
### Claude Desktop Connection Issues
- Verify paths in `claude_desktop_config.json` are correct
- Ensure `dist/index.js` exists (run `npm run build`)
- Check Claude Desktop logs: Settings → Developer → View Logs
- Restart Claude Desktop after configuration changes
## Development
```bash
npm run dev # Development mode with watch
npm run build # Build project
npm start # Run built server
npm run setup # Launch setup UI
npm run build:installer # Build macOS installer and uninstaller apps (requires Xcode)
```
## Security
- Never commit your `.env` file
- Enable PII masking (`MAILCHIMP_MASK_PII=true`)
- Use read-only API keys when possible
- Review [SECURITY.md](./SECURITY.md) for comprehensive security documentation
- Claude Desktop stores conversation history locally
## Contributing
Contributions welcome. Ensure code follows TypeScript best practices and includes proper input validation.
## License
MIT
## Support
- Check Troubleshooting section
- Review [SECURITY.md](./SECURITY.md)
- Open an issue on GitHub
