Klaviyo MCP Server

Implementation Reference

• src/tools/lists.js:13-25 (handler)

  Handler function for the 'get_lists' tool. Fetches lists from Klaviyo API using the generic klaviyoClient.get method, formats the response as a JSON string in a text content block, and handles errors by returning an error message.

  async (params) => {
    try {
      const lists = await klaviyoClient.get('/lists/', params);
      return {
        content: [{ type: "text", text: JSON.stringify(lists, null, 2) }]
      };
    } catch (error) {
      return {
        content: [{ type: "text", text: `Error retrieving lists: ${error.message}` }],
        isError: true
      };
    }
  },

• src/tools/lists.js:8-12 (schema)

  Zod schema defining the input parameters for the 'get_lists' tool: optional filter string, page_size (1-100), and page_cursor for pagination.

  {
    filter: z.string().optional().describe("Filter query for lists"),
    page_size: z.number().min(1).max(100).optional().describe("Number of lists per page (1-100)"),
    page_cursor: z.string().optional().describe("Cursor for pagination")
  },

• src/tools/lists.js:6-27 (registration)

  Direct registration of the 'get_lists' tool using server.tool(), specifying the name, input schema, execution handler, and description.

  server.tool(
    "get_lists",
    {
      filter: z.string().optional().describe("Filter query for lists"),
      page_size: z.number().min(1).max(100).optional().describe("Number of lists per page (1-100)"),
      page_cursor: z.string().optional().describe("Cursor for pagination")
    },
    async (params) => {
      try {
        const lists = await klaviyoClient.get('/lists/', params);
        return {
          content: [{ type: "text", text: JSON.stringify(lists, null, 2) }]
        };
      } catch (error) {
        return {
          content: [{ type: "text", text: `Error retrieving lists: ${error.message}` }],
          isError: true
        };
      }
    },
    { description: "Get lists from Klaviyo" }
  );

• src/server.js:33-33 (registration)

  Top-level invocation of registerListTools(server), which registers the 'get_lists' tool (and other list-related tools).

  registerListTools(server);

• src/klaviyo-client.js:135-180 (helper)

  Generic 'get' helper function used by the handler. Builds the API URL with query parameters (filter, page_size, page_cursor), performs the axios GET request via executeWithRetry (with caching, rate limiting retries), and handles Klaviyo-specific API formatting.

  export async function get(endpoint, params = {}, fallbackFn) {
    // Build the URL with query parameters according to Klaviyo API specs
    let url = endpoint;
    const queryParams = [];
    
    // Special handling for campaign endpoint - add required filter if missing
    if (endpoint === '/campaigns/' && !params.filter) {
      logger.debug('Adding default email filter for campaigns endpoint');
      params.filter = "equals(messages.channel,'email')";
    }
    
    // Handle filter parameter if provided
    if (params.filter) {
      queryParams.push(`filter=${encodeURIComponent(params.filter)}`);
    }
    
    // Handle include parameter if provided
    if (params.include) {
      queryParams.push(`include=${encodeURIComponent(params.include)}`);
    }
    
    // Handle page_size parameter if provided
    if (params.page_size) {
      queryParams.push(`page[size]=${params.page_size}`);
    }
    
    // Handle pagination cursor if provided
    if (params.page_cursor) {
      queryParams.push(`page[cursor]=${params.page_cursor}`);
    }
    
    // Add query parameters to URL
    if (queryParams.length > 0) {
      url = `${endpoint}?${queryParams.join('&')}`;
    }
    
    logger.debug(`Prepared GET request to: ${url}`);
    
    return executeWithRetry(
      () => client.get(url),
      'GET',
      endpoint,
      params,
      fallbackFn
    );
  }