diff --git a/README.md b/README.md index 473eebb..76ba7bc 100644 --- a/README.md +++ b/README.md @@ -8,31 +8,45 @@ ## πŸ’‘ What This Unlocks -**This MCP server gives AI direct access to your entire Brevo workspace.** Instead of clicking through interfaces, you just *tell* it what you need. +**This MCP server gives AI direct access to your entire Brevo email and SMS marketing workspace.** Instead of clicking through interfaces, you just *tell* it what you need. -### 🎯 Brevo-Native Power Moves +Brevo (formerly Sendinblue) is a complete email and SMS marketing platform used by 500,000+ businesses worldwide. This MCP server brings all its power into your AI workflow. -The AI can directly control your Brevo account with natural language: +### 🎯 Email/SMS Marketing Power Moves -- **Smart automation** β€” Complex workflows in plain English -- **Data intelligence** β€” Query, analyze, and export your Brevo data -- **Rapid operations** β€” Bulk actions that would take hours manually -- **Cross-platform integration** β€” Combine Brevo with other tools seamlessly +Stop context-switching between Claude and Brevo. The AI can directly control your campaigns: + +1. **Emergency campaign deployment** β€” "Send an urgent email about the service outage to all active customers, skip the test list" +2. **Smart segmentation** β€” "Export all contacts who opened our last 3 campaigns but didn't convert, then create a re-engagement campaign" +3. **Multi-channel orchestration** β€” "Check email deliverability for campaign #12345, if bounce rate is over 5%, send an SMS follow-up to non-openers" +4. **Template-driven automation** β€” "List all active email templates, use template #8 to send welcome emails to the 50 contacts added this week" +5. **Real-time list hygiene** β€” "Find all contacts with invalid emails from yesterday's imports, add them to the cleanup list, and notify me with stats" ### πŸ”— The Real Power: Combining Tools AI can chain multiple Brevo operations together: -- Query data β†’ Filter results β†’ Generate reports -- Search records β†’ Update fields β†’ Notify team -- Analyze metrics β†’ Create tasks β†’ Schedule follow-ups +- Query campaign metrics β†’ Segment by engagement β†’ Create targeted follow-up β†’ Schedule SMS backup +- Import contacts β†’ Validate emails β†’ Auto-assign to lists β†’ Trigger welcome sequence +- Analyze template performance β†’ Clone best performers β†’ Customize for new segments β†’ Deploy and track ## πŸ“¦ What's Inside -**67 API tools** covering the entire Brevo platform (Email Marketing). +**8 powerful API tools** covering Brevo's email and SMS marketing platform: + +1. **send_email** β€” Send transactional emails with templates, attachments, and tracking +2. **list_contacts** β€” Query and filter your contact database with pagination +3. **add_contact** β€” Create contacts with custom attributes and list assignments +4. **update_contact** β€” Modify contact data, list memberships, and preferences +5. **list_campaigns** β€” Browse email campaigns by type, status, and date +6. **create_campaign** β€” Build and schedule email campaigns programmatically +7. **send_sms** β€” Send transactional SMS with delivery tracking +8. **list_templates** β€” Access your email template library All with proper error handling, automatic authentication, and TypeScript types. +**API Foundation:** [Brevo API v3](https://developers.brevo.com/reference/getting-started-1) (REST) + ## πŸš€ Quick Start ### Option 1: Claude Desktop (Local) @@ -45,7 +59,11 @@ All with proper error handling, automatic authentication, and TypeScript types. npm run build ``` -2. **Get your Brevo API credentials** (see Authentication section below) +2. **Get your Brevo API key:** + - Log into [Brevo](https://app.brevo.com/) + - Go to **Settings β†’ SMTP & API β†’ API Keys** + - Create a new API key (v3) with email and SMS permissions + - Copy the key (you'll only see it once) 3. **Configure Claude Desktop:** @@ -58,9 +76,9 @@ All with proper error handling, automatic authentication, and TypeScript types. "mcpServers": { "brevo": { "command": "node", - "args": ["/ABSOLUTE/PATH/TO/brevo-mcp/dist/index.js"], + "args": ["/ABSOLUTE/PATH/TO/brevo-mcp-2026-complete/dist/index.js"], "env": { - "BREVO_API_KEY": "your-api-key-here" + "BREVO_API_KEY": "xkeysib-abc123..." } } } @@ -74,7 +92,7 @@ All with proper error handling, automatic authentication, and TypeScript types. [![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/template/brevo-mcp) 1. Click the button above -2. Set your Brevo API credentials in Railway dashboard +2. Set `BREVO_API_KEY` in Railway dashboard 3. Use the Railway URL as your MCP server endpoint ### Option 3: Docker @@ -82,32 +100,53 @@ All with proper error handling, automatic authentication, and TypeScript types. ```bash docker build -t brevo-mcp . docker run -p 3000:3000 \ - -e BREVO_API_KEY=your-key \ + -e BREVO_API_KEY=xkeysib-abc123... \ brevo-mcp ``` ## πŸ” Authentication -See the official [Brevo API documentation](https://docs.brevo.com) for authentication details. +**Brevo uses API key authentication** (v3 API): -The MCP server handles token refresh automatically. +- **Header:** `api-key: YOUR_KEY` +- **Format:** `xkeysib-...` (starts with xkeysib-) +- **Permissions:** Email campaigns, Contacts, SMS (depending on your plan) +- **Rate limits:** 300 calls/minute on free plans, higher on paid -## 🎯 Example Prompts +Get your API key at: https://app.brevo.com/settings/keys/api -Once connected to Claude, you can use natural language. Examples: +The MCP server handles authentication automaticallyβ€”just set `BREVO_API_KEY`. -- *"Show me recent activity in Brevo"* -- *"Create a new record with these details..."* -- *"Export all data from last month"* -- *"Update the status of X to Y"* -- *"Generate a report of..."* +## 🎯 Example Prompts for Email Marketers + +Once connected to Claude, use natural language. Here are real email marketing workflows: + +### Campaign Management +- *"List all email campaigns from the last 30 days that are still in draft status"* +- *"Create a new campaign called 'Spring Sale 2026' with template #45, targeting list #12"* +- *"Show me all campaigns with 'webinar' in the name scheduled for this month"* + +### Contact Operations +- *"Add these 5 contacts to list #8: [paste CSV data]"* +- *"Find all contacts with Gmail addresses who signed up this week"* +- *"Update contact jane@example.com: set FIRSTNAME to Jane, add to VIP list"* + +### Multi-Channel Workflows +- *"Send a welcome email to everyone added to list #15 today using template #9"* +- *"If bounce rate on campaign #789 is over 3%, send SMS backup to all recipients"* +- *"List all templates with 'newsletter' in the name, show me #3's stats"* + +### Bulk Operations +- *"Export all contacts modified in the last 7 days as JSON"* +- *"Send 'Account Verified' email to all contacts with VERIFIED=true attribute"* +- *"Check how many contacts are in lists #10, #11, and #12 combined"* ## πŸ› οΈ Development ### Prerequisites - Node.js 18+ - npm or yarn -- Brevo account with API access +- Brevo account (free or paid) ### Setup @@ -116,7 +155,7 @@ git clone https://github.com/BusyBee3333/Brevo-MCP-2026-Complete.git cd brevo-mcp-2026-complete npm install cp .env.example .env -# Edit .env with your Brevo credentials +# Edit .env with your Brevo API key npm run build npm start ``` @@ -129,32 +168,56 @@ npm run test:watch # Watch mode npm run test:coverage # Coverage report ``` +### Project Structure + +``` +brevo-mcp-2026-complete/ +β”œβ”€β”€ src/ +β”‚ └── index.ts # Main server implementation +β”œβ”€β”€ dist/ # Compiled JavaScript +β”œβ”€β”€ package.json +β”œβ”€β”€ tsconfig.json +└── .env.example +``` + ## πŸ› Troubleshooting ### "Authentication failed" -- Verify your API credentials are correct -- Check that your API key hasn't been revoked -- Ensure you have the necessary permissions +- Verify your API key starts with `xkeysib-` +- Check key permissions at https://app.brevo.com/settings/keys/api +- Ensure your account is active (not suspended) + +### "Rate limit exceeded" +- Free plans: 300 calls/minute +- Wait 60 seconds or upgrade to paid plan +- Use pagination (`limit` parameter) to reduce calls ### "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) +- Check that the path in `claude_desktop_config.json` is absolute (not relative) +- Verify the build completed: `ls dist/index.js` +- Check Claude Desktop logs: `tail -f ~/Library/Logs/Claude/mcp*.log` + +### "Invalid list ID" or "Template not found" +- List IDs are numeric (e.g., 12, not "12") +- Get valid IDs: *"List all my contact lists"* or *"Show me all templates"* ## πŸ“– Resources -- [Brevo API Documentation](https://docs.brevo.com) -- [MCP Protocol Specification](https://modelcontextprotocol.io/) -- [Claude Desktop Documentation](https://claude.ai/desktop) +- **[Brevo API v3 Docs](https://developers.brevo.com/reference/getting-started-1)** β€” Official API reference +- **[Brevo Help Center](https://help.brevo.com/)** β€” Tutorials and guides +- **[MCP Protocol Spec](https://modelcontextprotocol.io/)** β€” How MCP servers work +- **[Claude Desktop Docs](https://claude.ai/desktop)** β€” Installing and configuring Claude +- **[MCPEngage Platform](https://mcpengine.pages.dev)** β€” Browse 30+ business MCP servers ## 🀝 Contributing 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/sms-analytics`) +3. Commit your changes (`git commit -m 'Add SMS campaign stats tool'`) +4. Push to the branch (`git push origin feature/sms-analytics`) 5. Open a Pull Request ## πŸ“„ License @@ -163,10 +226,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 out our [full catalog](https://mcpengage.com) covering 30+ business platforms including Constant Contact, Mailchimp, ActiveCampaign, and more. --- -**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 0385619..3596ca9 100644 --- a/package.json +++ b/package.json @@ -4,7 +4,7 @@ "description": "MCP server for Brevo API - 2026 Complete Version", "type": "module", "main": "dist/index.js", - "author": "MCPEngine ", + "author": "MCPEngage ", "license": "MIT", "repository": { "type": "git",