smartlead-mcp-server

smartlead-mcp-server

1

The Smartlead MCP Server project offers robust tools for integrating and managing Smartlead campaigns through a Model Context Protocol (MCP) server. It supports a range of features from campaign creation to lead management, focusing on seamless integration and user customization options.

Smartlead MCP Server

This is a Model Context Protocol (MCP) server for Smartlead campaign management integration. It provides tools for creating and managing campaigns, updating campaign settings, and managing campaign sequences.

Features

  • Create new campaigns
  • Update campaign schedule settings
  • Update campaign general settings
  • Get campaign details
  • List all campaigns with filtering options
  • Manage campaign email sequences (save, get, update, delete)
  • Manage email accounts in campaigns (add, update, delete)
  • Manage leads in campaigns (add, update, delete)

Installation

  1. Clone the repository
  2. Install dependencies:
npm install
  1. Create a .env file based on .env.example and add your Smartlead API key:
SMARTLEAD_API_KEY=your_api_key_here
  1. Build the project:
npm run build

Usage

Standalone Usage

To start the server directly:

npm start

Integration with Claude

To use this MCP server with Claude, you need to add it to the MCP settings file:

  1. For Claude VSCode extension, add it to c:\Users\<username>\AppData\Roaming\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
  2. For Claude desktop app, add it to %APPDATA%\Claude\claude_desktop_config.json on Windows

Example configuration:

{
  "mcpServers": {
    "smartlead": {
      "command": "node",
      "args": ["E:/mcp-servers/smartlead/dist/index.js"],
      "env": {
        "SMARTLEAD_API_KEY": "your_api_key_here"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Replace your_api_key_here with your actual Smartlead API key.

Configuration

The server can be configured using environment variables:

  • SMARTLEAD_API_KEY (required): Your Smartlead API key
  • SMARTLEAD_API_URL (optional): Custom API URL (defaults to https://server.smartlead.ai/api/v1)
  • SMARTLEAD_RETRY_MAX_ATTEMPTS: Maximum retry attempts for API calls (default: 3)
  • SMARTLEAD_RETRY_INITIAL_DELAY: Initial delay in milliseconds for retries (default: 1000)
  • SMARTLEAD_RETRY_MAX_DELAY: Maximum delay in milliseconds for retries (default: 10000)
  • SMARTLEAD_RETRY_BACKOFF_FACTOR: Backoff factor for retry delays (default: 2)

Available Tools

smartlead_create_campaign

Create a new campaign in Smartlead.

Parameters:

  • name (required): Name of the campaign
  • client_id (optional): Client ID for the campaign

smartlead_update_campaign_schedule

Update a campaign's schedule settings.

Parameters:

  • campaign_id (required): ID of the campaign to update
  • timezone: Timezone for the campaign (e.g., "America/Los_Angeles")
  • days_of_the_week: Days of the week to send emails (1-7, where 1 is Monday)
  • start_hour: Start hour in 24-hour format (e.g., "09:00")
  • end_hour: End hour in 24-hour format (e.g., "17:00")
  • min_time_btw_emails: Minimum time between emails in minutes
  • max_new_leads_per_day: Maximum number of new leads per day
  • schedule_start_time: Schedule start time in ISO format

smartlead_update_campaign_settings

Update a campaign's general settings.

Parameters:

  • campaign_id (required): ID of the campaign to update
  • name: New name for the campaign
  • status: Status of the campaign (active, paused, completed)
  • settings: Additional campaign settings

smartlead_get_campaign

Get details of a specific campaign by ID.

Parameters:

  • campaign_id (required): ID of the campaign to retrieve

smartlead_list_campaigns

List all campaigns with optional filtering.

Parameters:

  • status: Filter campaigns by status (active, paused, completed, all)
  • limit: Maximum number of campaigns to return
  • offset: Offset for pagination

smartlead_save_campaign_sequence

Save a sequence of emails for a campaign with A/B testing variants.

Parameters:

  • campaign_id (required): ID of the campaign
  • sequences (required): Array of email sequence items, each with:
    • id: ID of the sequence (only for updates, omit when creating)
    • seq_number (required): Sequence number (order in the sequence)
    • seq_delay_details (required): Delay settings with:
      • delay_in_days (required): Days to wait before sending this email
    • variant_distribution_type: Type of variant distribution (MANUAL_EQUAL, MANUAL_PERCENTAGE, AI_EQUAL)
    • lead_distribution_percentage: Sample percentage size of the lead pool to use to find the winner
    • winning_metric_property: Metric to use for determining the winning variant (OPEN_RATE, CLICK_RATE, REPLY_RATE, POSITIVE_REPLY_RATE)
    • seq_variants: Array of email variants, each with:
      • subject (required): Email subject line
      • email_body (required): Email body content (HTML)
      • variant_label (required): Label for the variant (e.g., "A", "B", "C")
      • id: ID of the variant (only for updates, omit when creating)
      • variant_distribution_percentage: Percentage of leads to receive this variant
    • subject: Email subject line (for simple follow-ups, blank makes it in the same thread)
    • email_body: Email body content (HTML) for simple follow-ups

smartlead_get_campaign_sequence

Get the sequence of emails for a campaign.

Parameters:

  • campaign_id (required): ID of the campaign

smartlead_update_campaign_sequence

Update a specific email in a campaign sequence.

Parameters:

  • campaign_id (required): ID of the campaign
  • sequence_id (required): ID of the sequence email to update
  • subject: Updated email subject line
  • body: Updated email body content
  • wait_days: Updated days to wait before sending this email

smartlead_delete_campaign_sequence

Delete a specific email from a campaign sequence.

Parameters:

  • campaign_id (required): ID of the campaign
  • sequence_id (required): ID of the sequence email to delete

smartlead_add_email_account_to_campaign

Add an email account to a campaign.

Parameters:

  • campaign_id (required): ID of the campaign
  • email_account_id (required): ID of the email account to add

smartlead_update_email_account_in_campaign

Update an email account in a campaign.

Parameters:

  • campaign_id (required): ID of the campaign
  • email_account_id (required): ID of the email account to update
  • settings: Settings for the email account in this campaign

smartlead_delete_email_account_from_campaign

Remove an email account from a campaign.

Parameters:

  • campaign_id (required): ID of the campaign
  • email_account_id (required): ID of the email account to remove

smartlead_add_lead_to_campaign

Add leads to a campaign (up to 100 leads at once).

Parameters:

  • campaign_id (required): ID of the campaign
  • lead_list (required): Array of lead information objects (max 100), each with:
    • email (required): Email address of the lead
    • first_name: First name of the lead
    • last_name: Last name of the lead
    • company_name: Company name of the lead
    • phone_number: Phone number of the lead
    • website: Website of the lead
    • location: Location of the lead
    • custom_fields: Custom fields for the lead (max 20 fields)
    • linkedin_profile: LinkedIn profile URL of the lead
    • company_url: Company URL of the lead
  • settings: Settings for lead addition:
    • ignore_global_block_list: If true, uploaded leads will bypass the global block list
    • ignore_unsubscribe_list: If true, leads will bypass the comparison with unsubscribed leads
    • ignore_community_bounce_list: If true, uploaded leads will bypass any leads that bounced across the entire userbase
    • ignore_duplicate_leads_in_other_campaign: If true, leads will NOT bypass the comparison with other campaigns

smartlead_update_lead_in_campaign

Update a lead in a campaign.

Parameters:

  • campaign_id (required): ID of the campaign
  • lead_id (required): ID of the lead to update
  • lead (required): Updated lead information with:
    • email: Email address of the lead
    • first_name: First name of the lead
    • last_name: Last name of the lead
    • company: Company of the lead
    • custom_variables: Custom variables for the lead

smartlead_delete_lead_from_campaign

Remove a lead from a campaign.

Parameters:

  • campaign_id (required): ID of the campaign
  • lead_id (required): ID of the lead to remove

License

MIT