Klaviyo MCP Server

Implementation Reference

• src/tools/reporting.js:295-402 (handler)

  The core handler function that implements the tool logic. It fetches campaign details, attempts to get campaign message details, queries the campaign-values-reports API for metrics with fallback logic, formats a performance object, and returns it as JSON text content.
  async (params) => { try { logger.info(`Retrieving campaign performance for campaign ID: ${params.id}`); // First get the campaign details with fallback const campaignFallbackFn = async (error) => { logger.warn(`Error retrieving campaign details: ${error.message}. Using simplified approach.`); return { data: { attributes: { name: `Campaign ${params.id}`, send_time: new Date().toISOString() } } }; }; const campaign = await klaviyoClient.get(`/campaigns/${params.id}/`, {}, campaignFallbackFn); logger.debug(`Retrieved campaign details for ID: ${params.id}`); // Then get the campaign message to access the metrics (if available) let messageId; if (campaign.data.relationships && campaign.data.relationships['campaign-messages']?.data?.length) { messageId = campaign.data.relationships['campaign-messages'].data[0].id; try { await klaviyoClient.get(`/campaign-messages/${messageId}/`); logger.debug(`Retrieved campaign message details for message ID: ${messageId}`); } catch (messageError) { logger.warn(`Error retrieving message details: ${messageError.message}. Continuing with metrics only.`); } } else { logger.warn(`No campaign messages found for campaign ID: ${params.id}. Continuing with metrics only.`); } // Get campaign metrics using the updated Reporting API with valid statistics const payload = { data: { type: "campaign-values-report", attributes: { // Use only valid statistics - based on testing and API responses statistics: [ 'delivered', 'open_rate', 'click_rate', 'bounce_rate', 'unsubscribe_rate', 'revenue_per_recipient' ], timeframe: { key: "last_30_days" // Use a valid timeframe }, conversion_metric_id: API_CONFIG.defaultConversionMetricId, filter: FILTER_TEMPLATES.campaignId(params.id) } } }; logger.debug('Campaign performance request payload', payload); // Define the metrics fallback function const metricsFallbackFn = async (error) => { logger.warn(`Error retrieving comprehensive campaign metrics: ${error.message}. Attempting fallback.`); // Fallback to minimal statistics set const fallbackPayload = { data: { type: "campaign-values-report", attributes: { statistics: ['delivered'], timeframe: { key: "last_30_days" }, conversion_metric_id: API_CONFIG.defaultConversionMetricId, filter: FILTER_TEMPLATES.campaignId(params.id) } } }; logger.debug('Campaign performance fallback payload', fallbackPayload); return await klaviyoClient.post('/campaign-values-reports/', fallbackPayload); }; const metrics = await klaviyoClient.post('/campaign-values-reports/', payload, metricsFallbackFn); // Format the results for easier consumption const performance = { campaign_name: campaign.data.attributes.name, send_time: campaign.data.attributes.send_time, metrics: metrics.data.attributes }; logger.info(`Successfully retrieved campaign performance for campaign ID: ${params.id}`); return { content: [{ type: "text", text: JSON.stringify(performance, null, 2) }] }; } catch (error) { logger.error(`Failed to retrieve campaign performance: ${error.message}`, { campaignId: params.id }); return { content: [{ type: "text", text: `Error retrieving campaign performance: ${error.message}` }], isError: true }; } },
• src/tools/reporting.js:292-294 (schema)

  Zod validation schema for the tool input, requiring a campaign ID.
  { id: z.string().describe("ID of the campaign to retrieve performance for") },
• src/tools/reporting.js:290-404 (registration)

  The server.tool call within registerReportingTools that defines and registers the get_campaign_performance tool, including schema, handler, and description.
  server.tool( "get_campaign_performance", { id: z.string().describe("ID of the campaign to retrieve performance for") }, async (params) => { try { logger.info(`Retrieving campaign performance for campaign ID: ${params.id}`); // First get the campaign details with fallback const campaignFallbackFn = async (error) => { logger.warn(`Error retrieving campaign details: ${error.message}. Using simplified approach.`); return { data: { attributes: { name: `Campaign ${params.id}`, send_time: new Date().toISOString() } } }; }; const campaign = await klaviyoClient.get(`/campaigns/${params.id}/`, {}, campaignFallbackFn); logger.debug(`Retrieved campaign details for ID: ${params.id}`); // Then get the campaign message to access the metrics (if available) let messageId; if (campaign.data.relationships && campaign.data.relationships['campaign-messages']?.data?.length) { messageId = campaign.data.relationships['campaign-messages'].data[0].id; try { await klaviyoClient.get(`/campaign-messages/${messageId}/`); logger.debug(`Retrieved campaign message details for message ID: ${messageId}`); } catch (messageError) { logger.warn(`Error retrieving message details: ${messageError.message}. Continuing with metrics only.`); } } else { logger.warn(`No campaign messages found for campaign ID: ${params.id}. Continuing with metrics only.`); } // Get campaign metrics using the updated Reporting API with valid statistics const payload = { data: { type: "campaign-values-report", attributes: { // Use only valid statistics - based on testing and API responses statistics: [ 'delivered', 'open_rate', 'click_rate', 'bounce_rate', 'unsubscribe_rate', 'revenue_per_recipient' ], timeframe: { key: "last_30_days" // Use a valid timeframe }, conversion_metric_id: API_CONFIG.defaultConversionMetricId, filter: FILTER_TEMPLATES.campaignId(params.id) } } }; logger.debug('Campaign performance request payload', payload); // Define the metrics fallback function const metricsFallbackFn = async (error) => { logger.warn(`Error retrieving comprehensive campaign metrics: ${error.message}. Attempting fallback.`); // Fallback to minimal statistics set const fallbackPayload = { data: { type: "campaign-values-report", attributes: { statistics: ['delivered'], timeframe: { key: "last_30_days" }, conversion_metric_id: API_CONFIG.defaultConversionMetricId, filter: FILTER_TEMPLATES.campaignId(params.id) } } }; logger.debug('Campaign performance fallback payload', fallbackPayload); return await klaviyoClient.post('/campaign-values-reports/', fallbackPayload); }; const metrics = await klaviyoClient.post('/campaign-values-reports/', payload, metricsFallbackFn); // Format the results for easier consumption const performance = { campaign_name: campaign.data.attributes.name, send_time: campaign.data.attributes.send_time, metrics: metrics.data.attributes }; logger.info(`Successfully retrieved campaign performance for campaign ID: ${params.id}`); return { content: [{ type: "text", text: JSON.stringify(performance, null, 2) }] }; } catch (error) { logger.error(`Failed to retrieve campaign performance: ${error.message}`, { campaignId: params.id }); return { content: [{ type: "text", text: `Error retrieving campaign performance: ${error.message}` }], isError: true }; } }, { description: "Get a comprehensive performance summary for a campaign" } );
• src/server.js:38-38 (registration)

  Invocation of registerReportingTools on the MCP server, which registers the reporting tools including get_campaign_performance.
  registerReportingTools(server);