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 campaignget_campaign- Get campaign details by IDlist_campaigns- List all campaignsupdate_campaign_schedule- Update scheduling settingsupdate_campaign_settings- Update general settingsupdate_campaign_status- Pause, stop, or start campaignsdelete_campaign- Delete a campaignlist_campaign_email_accounts- List email accounts for a campaignadd_campaign_email_accounts- Add email accounts to a campaignremove_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 campaignpause_lead- Pause a lead in a campaignresume_lead- Resume a paused leaddelete_lead_from_campaign- Delete a lead from a campaignunsubscribe_lead_from_campaign- Unsubscribe lead from specific campaignget_lead_by_email- Get lead details by email addressunsubscribe_lead_globally- Unsubscribe lead from all campaignsget_lead_campaigns- Get all campaigns for a lead
Email Account Management (5 tools)
list_email_accounts- List all email accountsget_email_account- Get email account detailsupdate_warmup_settings- Configure email warmup settingsget_warmup_stats- Get warmup statistics (last 7 days)reconnect_failed_accounts- Reconnect failed email accounts
Analytics (3 tools)
get_campaign_statistics- Get detailed campaign statisticsget_campaign_analytics- Get top-level campaign analyticsget_campaign_analytics_by_date- Get analytics for a date range
Installation
- Install dependencies:
npm install
- Build the project:
npm run build
-
Get your Smartlead API key:
- Log in to Smartlead
- Navigate to Settings → Integrations
- Copy your API key
-
Set up environment variables:
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
{
"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 [email protected]"
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
npm run build
Watch mode (for development)
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:
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
.envfile 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
# 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
For MCP server issues, please open an issue on this repository.
