Klaviyo MCP Server

Implementation Reference

• src/tools/campaigns.js:11-28 (handler)

  Handler function that fetches campaigns from Klaviyo API. Applies default email channel filter if none provided, returns formatted JSON response or error message.

  async (params) => {
    try {
      // Always include the required channel filter if not already provided
      const apiParams = {
        filter: params.filter || "equals(messages.channel,'email')"
      };
      
      const campaigns = await klaviyoClient.get('/campaigns/', apiParams);
      return {
        content: [{ type: "text", text: JSON.stringify(campaigns, null, 2) }]
      };
    } catch (error) {
      return {
        content: [{ type: "text", text: `Error retrieving campaigns: ${error.message}` }],
        isError: true
      };
    }
  },

• src/tools/campaigns.js:8-10 (schema)

  Zod input schema defining optional 'filter' parameter for querying campaigns.

  {
    filter: z.string().optional().describe("Filter query for campaigns")
  },

• src/tools/campaigns.js:6-30 (registration)

  Direct registration of the get_campaigns tool on the MCP server within registerCampaignTools, including schema, handler, and description.

  server.tool(
    "get_campaigns",
    {
      filter: z.string().optional().describe("Filter query for campaigns")
    },
    async (params) => {
      try {
        // Always include the required channel filter if not already provided
        const apiParams = {
          filter: params.filter || "equals(messages.channel,'email')"
        };
        
        const campaigns = await klaviyoClient.get('/campaigns/', apiParams);
        return {
          content: [{ type: "text", text: JSON.stringify(campaigns, null, 2) }]
        };
      } catch (error) {
        return {
          content: [{ type: "text", text: `Error retrieving campaigns: ${error.message}` }],
          isError: true
        };
      }
    },
    { description: "Get campaigns from Klaviyo" }
  );

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

  Top-level invocation of registerCampaignTools in main server setup, which registers the get_campaigns tool among other campaign tools.

  registerCampaignTools(server);

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

  klaviyoClient.get utility function called by the handler. Handles API requests to Klaviyo with query param building (incl. campaigns filter), caching, exponential backoff retries for rate limits, and comprehensive error handling.

  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
    );
  }