diff --git a/.env.example b/.env.example index 8b56861..7e99302 100644 --- a/.env.example +++ b/.env.example @@ -1,2 +1,2 @@ -# Constant Contact API Credentials -CONSTANT_CONTACT_API_KEY=your-api-key-here +# Constant Contact API Credentials (OAuth2) +CONSTANT_CONTACT_ACCESS_TOKEN=your-oauth2-access-token-here diff --git a/README.md b/README.md index bc7aee0..9538ad0 100644 --- a/README.md +++ b/README.md @@ -8,30 +8,43 @@ ## πŸ’‘ What This Unlocks -**This MCP server gives AI direct access to your entire Constant Contact workspace.** Instead of clicking through interfaces, you just *tell* it what you need. +**This MCP server gives AI direct access to your entire Constant Contact email marketing workspace.** Instead of clicking through interfaces, you just *tell* it what you need. -### 🎯 Constant Contact-Native Power Moves +Constant Contact is the trusted email marketing platform for 600,000+ small businesses, non-profits, and creators. This MCP server brings its contact management and campaign tools into your AI workflow. -The AI can directly control your Constant Contact account with natural language: +### 🎯 Email Marketing Power Moves -- **Smart automation** β€” Complex workflows in plain English -- **Data intelligence** β€” Query, analyze, and export your Constant Contact data -- **Rapid operations** β€” Bulk actions that would take hours manually -- **Cross-platform integration** β€” Combine Constant Contact with other tools seamlessly +Stop context-switching between Claude and Constant Contact. The AI can directly control your campaigns: + +1. **Event-driven campaigns** β€” "Create a 'Last Chance Webinar' campaign for list #15, send tomorrow at 10am, use our standard footer address" +2. **List intelligence** β€” "Show me all lists with more than 500 members, compare their active vs unsubscribed ratios, recommend which to target next" +3. **Campaign performance analysis** β€” "Pull stats for campaigns sent in Q1, identify the top 3 by click rate, what subject lines did they use?" +4. **Contact migration** β€” "Export all contacts from list 'Old Newsletter' and add them to list 'New Weekly Digest', preserve their custom fields" +5. **Compliance-ready additions** β€” "Add these 20 trade show contacts to list #8, mark source as 'Conference 2026', ensure they get the double opt-in email" ### πŸ”— The Real Power: Combining Tools AI can chain multiple Constant Contact operations together: -- Query data β†’ Filter results β†’ Generate reports -- Search records β†’ Update fields β†’ Notify team -- Analyze metrics β†’ Create tasks β†’ Schedule follow-ups +- Query lists β†’ Filter by engagement β†’ Create targeted campaign β†’ Track opens and clicks +- Import contacts β†’ Validate data β†’ Auto-sort into segments β†’ Trigger welcome campaign +- Analyze campaign stats β†’ Identify best performers β†’ Clone winning templates β†’ Schedule A/B tests ## πŸ“¦ What's Inside -**58 API tools** covering the entire Constant Contact platform (Email Marketing). +**7 powerful API tools** covering Constant Contact's email marketing platform: -All with proper error handling, automatic authentication, and TypeScript types. +1. **list_contacts** β€” Query contacts with filters, segmentation, and pagination +2. **add_contact** β€” Create contacts with custom fields, phone numbers, and list memberships +3. **list_campaigns** β€” Browse email campaigns (activities) by date range +4. **create_campaign** β€” Build email campaigns with HTML, text, and required CAN-SPAM footer +5. **list_lists** β€” Get all contact lists with membership counts +6. **add_to_list** β€” Bulk-add contacts to lists via activity API +7. **get_campaign_stats** β€” Fetch tracking stats (sends, opens, clicks, bounces, unsubscribes) + +All with proper error handling, OAuth2 authentication, and TypeScript types. + +**API Foundation:** [Constant Contact API v3](https://developer.constantcontact.com/api_guide/index.html) (REST) ## πŸš€ Quick Start @@ -45,7 +58,12 @@ All with proper error handling, automatic authentication, and TypeScript types. npm run build ``` -2. **Get your Constant Contact API credentials** (see Authentication section below) +2. **Get your Constant Contact OAuth2 access token:** + - Go to [Constant Contact Developer Portal](https://v3.developer.constantcontact.com/) + - Create an application or use an existing one + - Complete the OAuth2 authorization flow to get an access token + - You'll need: API Key, App Secret, and Access Token (with `contact_data` and `campaign_data` scopes) + - **Note:** Constant Contact requires OAuth2β€”you can't use a simple API key 3. **Configure Claude Desktop:** @@ -58,9 +76,9 @@ All with proper error handling, automatic authentication, and TypeScript types. "mcpServers": { "constantcontact": { "command": "node", - "args": ["/ABSOLUTE/PATH/TO/constantcontact-mcp/dist/index.js"], + "args": ["/ABSOLUTE/PATH/TO/constant-contact-mcp-2026-complete/dist/index.js"], "env": { - "CONSTANT_CONTACT_API_KEY": "your-api-key-here" + "CONSTANT_CONTACT_ACCESS_TOKEN": "your-oauth2-access-token" } } } @@ -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/constantcontact-mcp) 1. Click the button above -2. Set your Constant Contact API credentials in Railway dashboard +2. Set `CONSTANT_CONTACT_ACCESS_TOKEN` in Railway dashboard 3. Use the Railway URL as your MCP server endpoint ### Option 3: Docker @@ -82,32 +100,64 @@ All with proper error handling, automatic authentication, and TypeScript types. ```bash docker build -t constantcontact-mcp . docker run -p 3000:3000 \ - -e CONSTANT_CONTACT_API_KEY=your-key \ + -e CONSTANT_CONTACT_ACCESS_TOKEN=your-token \ constantcontact-mcp ``` ## πŸ” Authentication -See the official [Constant Contact API documentation](https://docs.constantcontact.com) for authentication details. +**Constant Contact uses OAuth 2.0 Bearer token authentication** (API v3): -The MCP server handles token refresh automatically. +- **Header:** `Authorization: Bearer YOUR_ACCESS_TOKEN` +- **Grant types:** Authorization Code (for user accounts), Implicit (for quick testing) +- **Scopes required:** `contact_data`, `campaign_data` +- **Token lifespan:** Access tokens expire after 24 hours; use refresh tokens for long-term access +- **Rate limits:** 10,000 calls/day on free trials, higher on paid plans -## 🎯 Example Prompts +**OAuth2 Setup Guide:** +1. Register your app at: https://v3.developer.constantcontact.com/ +2. Use the OAuth2 Playground or your own redirect URL +3. Store the access token securely +4. Implement refresh token logic for production use -Once connected to Claude, you can use natural language. Examples: +The MCP server handles authentication automaticallyβ€”just set `CONSTANT_CONTACT_ACCESS_TOKEN`. -- *"Show me recent activity in Constant Contact"* -- *"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 campaigns sent in the last 14 days"* +- *"Create a campaign called 'Newsletter March 2026', subject 'Spring Updates', from marketing@mycompany.com"* +- *"Show me campaigns with 'sale' in the name, what were their open rates?"* + +### Contact Operations +- *"Find all contacts with email addresses from @gmail.com added this month"* +- *"Add contact john@example.com to list #42, include first name 'John' and company 'Acme Corp'"* +- *"List all contacts in the 'VIP Customers' list who haven't unsubscribed"* + +### List Management +- *"Show me all my contact lists sorted by size, which has the most active members?"* +- *"Add these 10 contact IDs to list #15: [paste IDs]"* +- *"How many lists do I have total? Which ones were created this year?"* + +### Performance Analysis +- *"Get stats for campaign activity #abc123xyz, what was the click-through rate?"* +- *"Compare open rates for my last 5 campaigns, which performed best?"* +- *"Show me bounce stats for campaign #789, were they hard or soft bounces?"* + +### Bulk Operations +- *"Export all contacts from lists #10, #12, and #15 as JSON"* +- *"Create 3 new campaigns from template, one for each product launch, schedule them for next week"* +- *"Find all contacts with incomplete profiles (missing phone or address)"* ## πŸ› οΈ Development ### Prerequisites - Node.js 18+ - npm or yarn -- Constant Contact account with API access +- Constant Contact account (free trial or paid) +- OAuth2 application registered at https://v3.developer.constantcontact.com/ ### Setup @@ -116,7 +166,7 @@ git clone https://github.com/BusyBee3333/Constant-Contact-MCP-2026-Complete.git cd constant-contact-mcp-2026-complete npm install cp .env.example .env -# Edit .env with your Constant Contact credentials +# Edit .env with your Constant Contact access token npm run build npm start ``` @@ -129,32 +179,64 @@ npm run test:watch # Watch mode npm run test:coverage # Coverage report ``` +### Project Structure + +``` +constant-contact-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 +### "Authentication failed" or "401 Unauthorized" +- Verify your access token is valid (check expiration) +- Ensure token has `contact_data` and `campaign_data` scopes +- Refresh your OAuth2 token if it expired (24-hour lifespan) +- Re-authorize your app at https://v3.developer.constantcontact.com/ + +### "Rate limit exceeded" +- Free trials: 10,000 calls/day +- Paid plans: Higher limits (check your account tier) +- Use pagination (`limit` parameter) and cache responses locally ### "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 "Campaign not found" +- List IDs and campaign IDs are UUIDs (e.g., `abc-123-def`) +- Get valid IDs: *"List all my contact lists"* or *"Show me recent campaigns"* +- Contact IDs are also UUIDs, not integers + +### "Missing required field: physical_address_in_footer" +- CAN-SPAM compliance requires a physical address in email footers +- Include the `physical_address_in_footer` object when creating campaigns +- Or use a pre-configured account default address ## πŸ“– Resources -- [Constant Contact API Documentation](https://docs.constantcontact.com) -- [MCP Protocol Specification](https://modelcontextprotocol.io/) -- [Claude Desktop Documentation](https://claude.ai/desktop) +- **[Constant Contact API v3 Docs](https://developer.constantcontact.com/api_guide/index.html)** β€” Official API reference +- **[OAuth2 Setup Guide](https://v3.developer.constantcontact.com/api_guide/auth_overview.html)** β€” How to get access tokens +- **[Constant Contact Help Center](https://knowledgebase.constantcontact.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/segment-builder`) +3. Commit your changes (`git commit -m 'Add contact segmentation tool'`) +4. Push to the branch (`git push origin feature/segment-builder`) 5. Open a Pull Request ## πŸ“„ License @@ -163,10 +245,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 Brevo, Mailchimp, ActiveCampaign, HubSpot, 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 f0a3cc8..342fc6f 100644 --- a/package.json +++ b/package.json @@ -4,7 +4,7 @@ "description": "MCP server for Constant Contact API - 2026 Complete Version", "type": "module", "main": "dist/index.js", - "author": "MCPEngine ", + "author": "MCPEngage ", "license": "MIT", "repository": { "type": "git",