Instantly MCP Server

Instructions

Implementation Reference

• src/handlers/lead-handler.ts:506-534 (handler)

  The handler function that implements the core logic for the 'create_lead_list' tool. It validates input, builds the API request to POST /lead-lists, and formats the MCP response.

  async function handleCreateLeadList(args: any, apiKey: string) {
    console.error('[Instantly MCP] 📋 Executing create_lead_list...');
  
    if (!args.name) {
      throw new McpError(ErrorCode.InvalidParams, 'Name is required for create_lead_list');
    }
  
    // Build list data with official API v2 parameters
    const listData: any = { name: args.name };
    if (args.has_enrichment_task !== undefined) listData.has_enrichment_task = args.has_enrichment_task;
    if (args.owned_by) listData.owned_by = args.owned_by;
  
    console.error(`[Instantly MCP] 📤 Creating lead list with data: ${JSON.stringify(listData, null, 2)}`);
  
    const createResult = await makeInstantlyRequest('/lead-lists', { method: 'POST', body: listData }, apiKey);
  
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify({
            success: true,
            lead_list: createResult,
            message: 'Lead list created successfully'
          }, null, 2)
        }
      ]
    };
  }

• src/tools/lead-tools.ts:117-131 (registration)

  The tool registration in the leadTools array, defining name, description, input schema, and annotations for the MCP server.

  {
    name: 'create_lead_list',
    title: 'Create Lead List',
    description: 'Create list. Set has_enrichment_task=true for auto-enrich.',
    annotations: { destructiveHint: false },
    inputSchema: {
      type: 'object',
      properties: {
        name: { type: 'string', description: 'List name' },
        has_enrichment_task: { type: 'boolean' },
        owned_by: { type: 'string', description: 'Owner UUID' }
      },
      required: ['name']
    }
  },

• src/validation.ts:517-521 (schema)

  Zod schema for validating inputs to the create_lead_list tool.

  export const CreateLeadListSchema = z.object({
    name: z.string().min(1, { message: 'Lead list name cannot be empty' }),
    has_enrichment_task: z.boolean().optional(),
    owned_by: z.string().optional()
  });

• src/validation.ts:752-754 (schema)

  Validation function specifically for create_lead_list inputs using the Zod schema.

  export function validateCreateLeadListData(args: unknown): z.infer<typeof CreateLeadListSchema> {
    return validateWithSchema(CreateLeadListSchema, args, 'create_lead_list');
  }

• src/handlers/lead-handler.ts:48-49 (registration)

  Switch case in handleLeadTool that routes 'create_lead_list' calls to the handler function.

  case 'create_lead_list':
    return handleCreateLeadList(args, apiKey);