Smartlead MCP Server

# Smartlead MCP Server A Model Context Protocol (MCP) server that provides AI assistants with access to the Smartlead API for managing email campaigns, leads, email accounts, and analytics. ## Features This MCP server exposes **28 tools** covering the core Smartlead API functionality: ### Campaign Management (10 tools) - `create_campaign` - Create a new email campaign - `get_campaign` - Get campaign details by ID - `list_campaigns` - List all campaigns - `update_campaign_schedule` - Update scheduling settings - `update_campaign_settings` - Update general settings - `update_campaign_status` - Pause, stop, or start campaigns - `delete_campaign` - Delete a campaign - `list_campaign_email_accounts` - List email accounts for a campaign - `add_campaign_email_accounts` - Add email accounts to a campaign - `remove_campaign_email_accounts` - Remove email accounts from a campaign ### Lead Management (9 tools) - `list_campaign_leads` - List leads in a campaign (with pagination) - `add_leads_to_campaign` - Add up to 100 leads to a campaign - `pause_lead` - Pause a lead in a campaign - `resume_lead` - Resume a paused lead - `delete_lead_from_campaign` - Delete a lead from a campaign - `unsubscribe_lead_from_campaign` - Unsubscribe lead from specific campaign - `get_lead_by_email` - Get lead details by email address - `unsubscribe_lead_globally` - Unsubscribe lead from all campaigns - `get_lead_campaigns` - Get all campaigns for a lead ### Email Account Management (5 tools) - `list_email_accounts` - List all email accounts - `get_email_account` - Get email account details - `update_warmup_settings` - Configure email warmup settings - `get_warmup_stats` - Get warmup statistics (last 7 days) - `reconnect_failed_accounts` - Reconnect failed email accounts ### Analytics (3 tools) - `get_campaign_statistics` - Get detailed campaign statistics - `get_campaign_analytics` - Get top-level campaign analytics - `get_campaign_analytics_by_date` - Get analytics for a date range ## Installation 1. **Install dependencies:** ```bash npm install ``` 2. **Build the project:** ```bash npm run build ``` 3. **Get your Smartlead API key:** - Log in to [Smartlead](https://app.smartlead.ai) - Navigate to Settings → Integrations - Copy your API key 4. **Set up environment variables:** ```bash cp .env.example .env # Edit .env and add your API key ``` ## Configuration ### For Claude Desktop Add this configuration to your Claude Desktop config file: **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` ```json { "mcpServers": { "smartlead": { "command": "node", "args": ["/absolute/path/to/smartlead-mcp/build/index.js"], "env": { "SMARTLEAD_API_KEY": "your_api_key_here" } } } } ``` ### For Other MCP Clients Use the standard MCP server connection with: - **Command:** `node /path/to/smartlead-mcp/build/index.js` - **Environment:** `SMARTLEAD_API_KEY=your_api_key_here` ## Usage Examples Once configured, you can use natural language to interact with Smartlead through your AI assistant: ### Campaign Management ``` "Create a new campaign called 'Q1 Outreach'" "List all my campaigns" "Update the campaign schedule to run Monday-Friday 9am-5pm EST" "Pause campaign 12345" ``` ### Lead Management ``` "Add these 5 leads to campaign 12345: [lead data]" "Show me all leads in campaign 12345" "Pause lead 67890 in campaign 12345" "Get all campaigns for the lead with email john@example.com" ``` ### Email Accounts ``` "List all my email accounts" "Get warmup stats for email account 456" "Enable warmup for email account 456 with 20 emails per day" ``` ### Analytics ``` "Get analytics for campaign 12345" "Show me campaign statistics for campaign 12345 from 2025-01-01 to 2025-01-31" "Get top-level analytics for campaign 12345" ``` ## Development ### Build ```bash npm run build ``` ### Watch mode (for development) ```bash npm run watch ``` ### Project Structure ``` smartlead-mcp/ ├── src/ │ ├── index.ts # Main MCP server entry point │ ├── smartlead-client.ts # API client wrapper │ ├── tools/ # MCP tool implementations │ │ ├── campaigns.ts # Campaign management tools │ │ ├── leads.ts # Lead management tools │ │ ├── email-accounts.ts # Email account tools │ │ └── analytics.ts # Analytics tools │ └── types/ │ └── smartlead.ts # TypeScript type definitions ├── openapi.yaml # OpenAPI spec reference ├── package.json ├── tsconfig.json └── README.md ``` ## API Reference This MCP server is built on the Smartlead API. For detailed API documentation, see: - [Smartlead API Documentation](https://api.smartlead.ai/reference/welcome) - [Authentication Guide](https://api.smartlead.ai/reference/authentication) ## Security - **Never commit your API key** to version control - API keys are passed as query parameters to the Smartlead API (per their API design) - Store your API key in environment variables only - The `.env` file is gitignored by default ## Troubleshooting ### API Key Not Found ``` Error: SMARTLEAD_API_KEY environment variable is required ``` **Solution:** Make sure you've set the `SMARTLEAD_API_KEY` environment variable in your MCP client configuration. ### API Errors The server provides detailed error messages from the Smartlead API. Common issues: - **401 Unauthorized:** Invalid API key - **404 Not Found:** Campaign/Lead/Account ID doesn't exist - **429 Too Many Requests:** Rate limit exceeded (wait and retry) ### Build Errors ```bash # Clean build directory and rebuild rm -rf build/ npm run build ``` ## License MIT ## Contributing Contributions are welcome! Please feel free to submit issues or pull requests. ## Support For Smartlead API issues, contact [Smartlead Support](https://www.smartlead.ai) For MCP server issues, please open an issue on this repository.