Klaviyo MCP Server

Implementation Reference

• src/tools/reporting.js:23-112 (handler)

  The handler function that executes the get_campaign_metrics tool. It constructs a payload for the Klaviyo /campaign-values-reports/ endpoint, handles timeframe and statistics validation, includes fallback logic, and returns formatted results or error.
  async (params) => { try { logger.info(`Retrieving campaign metrics for campaign ID: ${params.id}`); // Prepare statistics list with valid names const statistics = params.metrics || DEFAULT_STATISTICS.standard; // Validate statistics to ensure they're supported by the API const validatedStatistics = statistics.filter(stat => VALID_CAMPAIGN_STATISTICS.includes(stat)); if (validatedStatistics.length === 0) { logger.warn(`No valid statistics provided for campaign metrics. Using default: ${DEFAULT_STATISTICS.basic}`); validatedStatistics.push(...DEFAULT_STATISTICS.basic); } // Create payload for the reporting API const payload = { data: { type: "campaign-values-report", attributes: { statistics: validatedStatistics, filter: FILTER_TEMPLATES.campaignId(params.id), conversion_metric_id: params.conversion_metric_id || API_CONFIG.defaultConversionMetricId } } }; // Add timeframe - either predefined or custom dates if (params.start_date && params.end_date) { payload.data.attributes.timeframe = { start: params.start_date, end: params.end_date }; logger.debug(`Using custom timeframe: ${params.start_date} to ${params.end_date}`); } else { // Default to last 30 days payload.data.attributes.timeframe = { key: API_CONFIG.defaultTimeframe }; logger.debug(`Using default timeframe: ${API_CONFIG.defaultTimeframe}`); } logger.debug('Campaign metrics request payload', payload); // Define the fallback function const fallbackFn = async (error) => { logger.warn(`Error retrieving campaign metrics with initial parameters: ${error.message}. Attempting fallback.`); // Fallback to minimal statistics set const fallbackPayload = { data: { type: "campaign-values-report", attributes: { statistics: DEFAULT_STATISTICS.basic, timeframe: { key: API_CONFIG.defaultTimeframe }, conversion_metric_id: API_CONFIG.defaultConversionMetricId, filter: FILTER_TEMPLATES.campaignId(params.id) } } }; logger.debug('Campaign metrics fallback payload', fallbackPayload); const fallbackResults = await klaviyoClient.post('/campaign-values-reports/', fallbackPayload); logger.info(`Successfully retrieved basic campaign metrics for campaign ID: ${params.id} using fallback`); return fallbackResults; }; // Use the post method with the fallback function const results = await klaviyoClient.post('/campaign-values-reports/', payload, fallbackFn); logger.info(`Successfully retrieved campaign metrics for campaign ID: ${params.id}`); return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] }; } catch (error) { logger.error(`Failed to retrieve campaign metrics (including fallback attempt): ${error.message}`, { campaignId: params.id }); return { content: [{ type: "text", text: `Error retrieving campaign metrics (including fallback attempt): ${error.message}` }], isError: true }; } },
• src/tools/reporting.js:16-22 (schema)

  Zod schema defining the input parameters for the get_campaign_metrics tool: campaign ID (required), optional metrics list, date range, and conversion metric ID.
  { id: z.string().describe("ID of the campaign to retrieve metrics for"), metrics: z.array(z.string()).optional().describe("Specific metrics to retrieve (e.g., ['open_rate', 'click_rate', 'delivered', 'bounce_rate'])"), start_date: z.string().optional().describe("Start date for metrics (ISO format)"), end_date: z.string().optional().describe("End date for metrics (ISO format)"), conversion_metric_id: z.string().optional().describe("ID of the metric to use for conversion statistics") },
• src/tools/reporting.js:14-114 (registration)

  Direct registration of the get_campaign_metrics tool using server.tool within the registerReportingTools function.
  server.tool( "get_campaign_metrics", { id: z.string().describe("ID of the campaign to retrieve metrics for"), metrics: z.array(z.string()).optional().describe("Specific metrics to retrieve (e.g., ['open_rate', 'click_rate', 'delivered', 'bounce_rate'])"), start_date: z.string().optional().describe("Start date for metrics (ISO format)"), end_date: z.string().optional().describe("End date for metrics (ISO format)"), conversion_metric_id: z.string().optional().describe("ID of the metric to use for conversion statistics") }, async (params) => { try { logger.info(`Retrieving campaign metrics for campaign ID: ${params.id}`); // Prepare statistics list with valid names const statistics = params.metrics || DEFAULT_STATISTICS.standard; // Validate statistics to ensure they're supported by the API const validatedStatistics = statistics.filter(stat => VALID_CAMPAIGN_STATISTICS.includes(stat)); if (validatedStatistics.length === 0) { logger.warn(`No valid statistics provided for campaign metrics. Using default: ${DEFAULT_STATISTICS.basic}`); validatedStatistics.push(...DEFAULT_STATISTICS.basic); } // Create payload for the reporting API const payload = { data: { type: "campaign-values-report", attributes: { statistics: validatedStatistics, filter: FILTER_TEMPLATES.campaignId(params.id), conversion_metric_id: params.conversion_metric_id || API_CONFIG.defaultConversionMetricId } } }; // Add timeframe - either predefined or custom dates if (params.start_date && params.end_date) { payload.data.attributes.timeframe = { start: params.start_date, end: params.end_date }; logger.debug(`Using custom timeframe: ${params.start_date} to ${params.end_date}`); } else { // Default to last 30 days payload.data.attributes.timeframe = { key: API_CONFIG.defaultTimeframe }; logger.debug(`Using default timeframe: ${API_CONFIG.defaultTimeframe}`); } logger.debug('Campaign metrics request payload', payload); // Define the fallback function const fallbackFn = async (error) => { logger.warn(`Error retrieving campaign metrics with initial parameters: ${error.message}. Attempting fallback.`); // Fallback to minimal statistics set const fallbackPayload = { data: { type: "campaign-values-report", attributes: { statistics: DEFAULT_STATISTICS.basic, timeframe: { key: API_CONFIG.defaultTimeframe }, conversion_metric_id: API_CONFIG.defaultConversionMetricId, filter: FILTER_TEMPLATES.campaignId(params.id) } } }; logger.debug('Campaign metrics fallback payload', fallbackPayload); const fallbackResults = await klaviyoClient.post('/campaign-values-reports/', fallbackPayload); logger.info(`Successfully retrieved basic campaign metrics for campaign ID: ${params.id} using fallback`); return fallbackResults; }; // Use the post method with the fallback function const results = await klaviyoClient.post('/campaign-values-reports/', payload, fallbackFn); logger.info(`Successfully retrieved campaign metrics for campaign ID: ${params.id}`); return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] }; } catch (error) { logger.error(`Failed to retrieve campaign metrics (including fallback attempt): ${error.message}`, { campaignId: params.id }); return { content: [{ type: "text", text: `Error retrieving campaign metrics (including fallback attempt): ${error.message}` }], isError: true }; } }, { description: "Get performance metrics for a specific campaign (open rates, click rates, etc.)" } );
• src/server.js:38-38 (registration)

  Invocation of registerReportingTools(server) which includes the registration of get_campaign_metrics along with other reporting tools.
  registerReportingTools(server);