Instantly MCP Server

Instructions

Implementation Reference

• src/handlers/lead-handler.ts:199-250 (handler)

  Core handler function that executes the create_lead tool logic: builds lead data from args and makes POST request to Instantly.ai /leads endpoint.

  async function handleCreateLead(args: any, apiKey: string) {
    console.error('[Instantly MCP] 👤 Executing create_lead...');
  
    // Build lead data with all supported parameters from Instantly.ai API v2
    const leadData: any = {};
  
    // Core lead information
    if (args.campaign) leadData.campaign = args.campaign;
    if (args.email) leadData.email = args.email;
    if (args.first_name) leadData.first_name = args.first_name;
    if (args.last_name) leadData.last_name = args.last_name;
    if (args.company_name) leadData.company_name = args.company_name;
    if (args.phone) leadData.phone = args.phone;
    if (args.website) leadData.website = args.website;
    if (args.personalization) leadData.personalization = args.personalization;
  
    // Advanced parameters
    if (args.lt_interest_status !== undefined) leadData.lt_interest_status = args.lt_interest_status;
    if (args.pl_value_lead) leadData.pl_value_lead = args.pl_value_lead;
    if (args.list_id) leadData.list_id = args.list_id;
    if (args.assigned_to) leadData.assigned_to = args.assigned_to;
  
    // Skip conditions
    if (args.skip_if_in_workspace !== undefined) leadData.skip_if_in_workspace = args.skip_if_in_workspace;
    if (args.skip_if_in_campaign !== undefined) leadData.skip_if_in_campaign = args.skip_if_in_campaign;
    if (args.skip_if_in_list !== undefined) leadData.skip_if_in_list = args.skip_if_in_list;
  
    // Verification and blocklist
    if (args.blocklist_id) leadData.blocklist_id = args.blocklist_id;
    if (args.verify_leads_for_lead_finder !== undefined) leadData.verify_leads_for_lead_finder = args.verify_leads_for_lead_finder;
    if (args.verify_leads_on_import !== undefined) leadData.verify_leads_on_import = args.verify_leads_on_import;
  
    // Custom variables
    if (args.custom_variables) leadData.custom_variables = args.custom_variables;
  
    console.error(`[Instantly MCP] 📤 Creating lead with data: ${JSON.stringify(leadData, null, 2)}`);
  
    const createResult = await makeInstantlyRequest('/leads', { method: 'POST', body: leadData }, apiKey);
  
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify({
            success: true,
            lead: createResult,
            message: 'Lead created successfully'
          }, null, 2)
        }
      ]
    };
  }

• src/tools/lead-tools.ts:47-75 (registration)

  MCP tool registration/definition including name, description, annotations, and inputSchema for create_lead.

  {
    name: 'create_lead',
    title: 'Create Lead',
    description: 'Create lead with custom variables. Use skip_if_in_campaign to prevent duplicates.',
    annotations: { destructiveHint: false },
    inputSchema: {
      type: 'object',
      properties: {
        campaign: { type: 'string', description: 'Campaign UUID' },
        email: { type: 'string', description: 'Required' },
        first_name: { type: 'string' },
        last_name: { type: 'string' },
        company_name: { type: 'string' },
        phone: { type: 'string' },
        website: { type: 'string' },
        personalization: { type: 'string' },
        lt_interest_status: { type: 'number', description: '-3 to 4' },
        pl_value_lead: { type: 'string' },
        list_id: { type: 'string' },
        assigned_to: { type: 'string' },
        skip_if_in_workspace: { type: 'boolean' },
        skip_if_in_campaign: { type: 'boolean', description: 'Recommended' },
        skip_if_in_list: { type: 'boolean' },
        blocklist_id: { type: 'string' },
        verify_leads_on_import: { type: 'boolean' },
        custom_variables: { type: 'object', description: 'Match campaign field names' }
      }
    }
  },

• src/validation.ts:455-484 (schema)

  Zod schema for validating create_lead input parameters, matching the tool's inputSchema.

  export const CreateLeadSchema = z.object({
    // Core lead information
    campaign: z.string().optional(),
    email: z.string().email().optional(),
    first_name: z.string().optional(),
    last_name: z.string().optional(),
    company_name: z.string().optional(),
    phone: z.string().optional(),
    website: z.string().url().optional(),
    personalization: z.string().optional(),
  
    // Advanced parameters
    lt_interest_status: z.number().int().min(-3).max(4).optional(),
    pl_value_lead: z.string().optional(),
    list_id: z.string().optional(),
    assigned_to: z.string().optional(),
  
    // Skip conditions
    skip_if_in_workspace: z.boolean().optional(),
    skip_if_in_campaign: z.boolean().optional(),
    skip_if_in_list: z.boolean().optional(),
  
    // Verification and blocklist
    blocklist_id: z.string().optional(),
    verify_leads_for_lead_finder: z.boolean().optional(),
    verify_leads_on_import: z.boolean().optional(),
  
    // Custom variables
    custom_variables: z.record(z.string(), z.any()).optional()
  });

• src/validation.ts:731-733 (schema)

  Validation wrapper function that applies CreateLeadSchema to input args for create_lead tool.

  export function validateCreateLeadData(args: unknown): z.infer<typeof CreateLeadSchema> {
    return validateWithSchema(CreateLeadSchema, args, 'create_lead');
  }

• src/handlers/lead-handler.ts:30-31 (registration)

  Dispatch case in handleLeadTool switch statement that routes create_lead calls to the handler function.

  case 'create_lead':
    return handleCreateLead(args, apiKey);