Brevo MCP Server

MCP (Model Context Protocol) server for Brevo email marketing platform with comprehensive campaign management, analytics, and automation capabilities.

🚀 Key Features

📧 Campaign Management

• Create sophisticated email campaigns with A/B testing and segmentation
• Update campaign content, recipients, and scheduling
• Send campaigns immediately or schedule for optimal times
• Test campaigns using pre-configured test lists before full send
• Control campaign status (pause, resume, archive, replicate)
• Share campaign templates via unique URLs

📊 Advanced Analytics

• Campaign Performance - Open rates, click rates, bounce analysis
• Contact Engagement - Track subscriber behaviour and preferences
• Comparative Analysis - Benchmark campaigns against industry averages
• Real-time Insights - AI-powered recommendations for improvement
• Recipient-level Data - Granular tracking of individual interactions

🔧 Automation & Integration

• Transactional Emails - Send personalised emails via API
• Template Management - Use and share email templates
• Contact Segmentation - Target specific audience groups
• Smart Send Times - Optimise delivery for maximum engagement
• UTM Tracking - Integrate with analytics platforms

🎯 Smart Features

• Test List Integration - Safe testing workflow with pre-configured test lists
• IP Warmup - Gradually increase sending volume
• A/B Testing - Test subject lines and content variations (Business/Enterprise plans only)
• Best Time Sending - AI-optimised send times per recipient
• List Management - Include/exclude lists dynamically
• Bulk Operations - Handle thousands of contacts efficiently

Campaign Workflow

Recommended Campaign Testing & Sending Process

1. Setup Test List in Brevo

   • Configure your test list in Brevo Settings
   • Add test email addresses to the list
   • This is a one-time setup

2. Create Campaign

   Use: create_email_campaign
   - Set name, subject
   - Add HTML content or template
   - Configure recipient lists
   - Sender auto-detected (or specify custom)

3. Test Campaign

   Use: send_test_email
   - Provide only campaignId
   - Automatically sends to your test list
   - Review the test email

4. Update if Needed

   Use: update_email_campaign
   - Modify content, subject, etc.
   - Re-test as needed

5. Send Campaign

   Use: send_campaign_now
   - Sends to all configured recipients
   - Or schedule with scheduledAt parameter

Important Notes

• Test List: The MCP assumes you have a pre-configured test list in Brevo
• send_test_email: By default sends to your test list (omit emailTo parameter)
• Safety: Always test before sending to actual recipients
• No Duplicate: The duplicate campaign feature is not available in Brevo API

Installation

Quick Start

1. Install via npm:

   npm install -g @houtini/brevo-mcp

2. Configure Claude Desktop: Add this to your claude_desktop_config.json:

   {
     "mcpServers": {
       "brevo": {
         "command": "npx",
         "args": ["-y", "@houtini/brevo-mcp"],
         "env": {
           "BREVO_API_KEY": "your-brevo-api-key-here"
         }
       }
     }
   }

3. Restart Claude Desktop

Manual Installation

1. Clone this repository:

   git clone https://github.com/houtini-ai/brevo-mcp.git
   cd brevo-mcp
   npm install
   npm run build

2. Add to Claude Desktop config:

   {
     "mcpServers": {
       "brevo": {
         "command": "node",
         "args": ["C:/path/to/brevo-mcp/dist/index.js"],
         "env": {
           "BREVO_API_KEY": "your-brevo-api-key-here"
         }
       }
     }
   }

Configuration

Environment Variables

• BREVO_API_KEY - Your standard Brevo v3 API key (required)
  • Must be the standard API key that starts with xkeysib-
  • Found in Brevo Dashboard → Settings → API Keys
  • Note: MCP-specific API keys will be supported in a future release
• BREVO_BASE_URL - Custom API base URL (optional, defaults to https://api.brevo.com/v3)

Getting Your API Key

1. Log in to your Brevo account
2. Go to Settings → API Keys
3. Use the Standard API Key (not the MCP API key)
   • The standard v3 API key starts with xkeysib-
   • MCP API key support coming in a future release
4. Create a new API key or copy an existing one
5. Important: You may need to whitelist your IP address in Brevo's security settings

📮 Sender Configuration

Intelligent Sender Management

The MCP automatically detects and uses your verified sender, making campaign creation simpler and safer:

Default Behaviour

• Auto-detection: If no sender is specified, the MCP automatically uses your verified sender from existing campaigns
• Smart fallback: Checks sent campaigns first, then draft campaigns if needed
• Safety first: All test emails use the verified sender to prevent delivery issues

How It Works

// Option 1: Auto-detect sender (RECOMMENDED)
create_email_campaign({
  name: "My Campaign",
  subject: "Hello World",
  htmlContent: "<h1>Content</h1>"
  // No sender needed - uses verified sender automatically
})

// Option 2: Specify sender by ID (for specific IP pools)
create_email_campaign({
  name: "My Campaign",
  subject: "Hello World",
  htmlContent: "<h1>Content</h1>",
  sender: {
    name: "Custom Name",
    id: 2  // Your sender ID from Brevo
  }
})

// Option 3: Specify sender by email (must be verified)
create_email_campaign({
  name: "My Campaign",
  subject: "Hello World",
  htmlContent: "<h1>Content</h1>",
  sender: {
    name: "Custom Name",
    email: "[email protected]"
  }
})

Finding Your Sender ID

To find your sender ID, check any existing campaign:

get_email_campaigns({ limit: 1 })
// Response includes: sender: { id: 2, email: "...", name: "..." }

Important Notes

• Verified senders only: Email addresses must be verified in Brevo before use
• Test emails: Always sent from the verified sender for reliability
• IP Pools: Use sender ID (not email) if you have dedicated IP pools
• First-time setup: Create at least one campaign in Brevo dashboard to establish a verified sender

🎯 Quick Start Guide

Once configured, try these commands to get started:

1. Check your setup: "Show my Brevo account info"
2. View campaigns: "List my email campaigns"
3. Create a campaign: "Create a new email campaign called 'Newsletter'"
4. Send a test: "Send a test email for campaign ID 123"
5. Check performance: "Show analytics for my campaigns this week"
6. Manage campaigns: "Pause campaign ID 456"

The MCP server understands natural language, so you can phrase requests conversationally!

Available Tools

📋 Account & Contacts

• get_account_info - View account details, plan, credits, and features
• get_contacts - List, search, and filter contacts with pagination
• get_contact_analytics - Analyse contact engagement and activity history

📧 Campaign Creation & Management

• create_email_campaign - Create campaigns with rich configuration options
  • HTML content, templates, or external URLs
  • List targeting with inclusion/exclusion rules
  • A/B testing and send time optimisation
  • Scheduling and automation triggers
• update_email_campaign - Modify any aspect of existing campaigns

🚀 Campaign Delivery

• send_campaign_now - Send campaigns immediately to recipients
• send_test_email - Test campaigns with specific email addresses
• update_campaign_status - Control campaign state:
  • suspended - Pause sending
  • archive/darchive - Archive or restore
  • queued - Queue for sending
  • replicate - Create working copy

📊 Analytics & Insights

• get_email_campaigns - List campaigns with filtering by status/type
• get_campaign_analytics - Detailed metrics for specific campaigns:
  • Delivery, open, and click rates
  • Bounce and unsubscribe analysis
  • Geographic and device breakdowns
• get_campaigns_performance - Compare multiple campaigns:
  • Performance scoring and ranking
  • Trend analysis over time
  • Top performer identification
• get_analytics_summary - Comprehensive dashboard view:
  • Account-wide statistics
  • Period comparisons
  • AI-powered insights and recommendations
• get_campaign_recipients - Recipient-level engagement data

📨 Transactional Email

• send_email - Send individual transactional emails:
  • Template-based or custom HTML
  • Dynamic personalisation
  • Attachment support
  • Reply tracking

🎨 Template Management

• get_shared_template_url - Generate shareable template links

Usage Examples

Campaign Creation Workflow

User: "Create a new email campaign for our Black Friday sale"
Assistant: "I'll create the Black Friday campaign. What's your sender email and target list?"

User: "Use [email protected] and send to list ID 5"
Assistant: [Creates campaign with professional template and scheduling options]

Campaign Management

User: "Update our newsletter campaign with new content"
Assistant: [Updates campaign content and configuration]

User: "Schedule it for next Tuesday at 10am"
Assistant: [Updates campaign with optimal send time]

User: "Send a test to [email protected] first"
Assistant: [Sends test email for review]

Analytics & Insights

User: "How are our email campaigns performing this quarter?"
Assistant: [Displays comprehensive metrics with trends and recommendations]

User: "Which campaigns had the best engagement?"
Assistant: [Shows top performers with detailed breakdowns]

Advanced Operations

User: "Pause all active campaigns"
Assistant: [Updates status of all running campaigns]

User: "Create an A/B test for our welcome email"
Assistant: [Sets up split test with subject line variations - requires Business/Enterprise plan]

Feature Reference

Campaign Creation Parameters

When creating campaigns, you can specify:

• Content Options
  • htmlContent - Direct HTML content
  • htmlUrl - URL to fetch HTML from
  • templateId - Use existing Brevo template
• Recipient Configuration
  • listIds - Target specific lists
  • exclusionListIds - Exclude certain lists
  • segmentIds - Use dynamic segments
• Advanced Features
  • scheduledAt - Schedule for specific time
  • sendAtBestTime - AI-optimised delivery
  • abTesting - Enable split testing (requires Business/Enterprise plan)
  • ipWarmupEnable - Gradual volume increase
  • utmCampaign - Analytics tracking

Campaign Status Values

Control your campaigns with these status options:

• suspended - Temporarily pause sending
• archive - Move to archive (hidden from main view)
• darchive - Restore from archive
• queued - Add to send queue
• sent - Mark as sent
• replicate - Create editable copy

Analytics Periods

Available time ranges for analytics:

• today - Current day statistics
• yesterday - Previous day metrics
• last7days - Week-to-date performance
• last30days - Month-to-date analysis
• custom - Specify exact date range

Performance Metrics

Track these key performance indicators:

• Delivery Metrics: Sent, delivered, bounced
• Engagement Metrics: Opens, clicks, forwards
• List Health: Unsubscribes, complaints, list growth
• Comparative Analysis: Industry benchmarks, trend analysis

Troubleshooting

Server Won't Start

• Ensure Node.js 18+ is installed
• Check the logs at: %APPDATA%\Claude\logs\mcp-server-brevo.log

API Key Issues

• The server starts without an API key but will prompt you when needed
• Add the key to your Claude config and restart Claude Desktop
• Ensure your IP is whitelisted in Brevo if you get authentication errors

Common Errors

• 401 Unauthorized: Check API key and IP whitelist in Brevo
• 429 Rate Limited: You've exceeded Brevo's API rate limits
• 404 Not Found: The resource doesn't exist or endpoint is incorrect

Development

Building from Source

npm install
npm run build
npm test

Running Tests

# Test without API key
npm test

# Test with API key
BREVO_API_KEY=your-key npm test

License

MIT © Houtini Ltd

Support

• Issues: GitHub Issues
• Email: [email protected]
• Documentation: Brevo API Docs