Klaviyo MCP Server Enhanced

A comprehensive Model Context Protocol (MCP) server for interacting with the Klaviyo API. This enhanced version provides advanced analytics capabilities, performance optimizations, and robust error handling while maintaining full compatibility with the original MCP server.

🌟 Key Features

• Advanced Analytics & Reporting: Access campaign performance metrics, aggregated data, and detailed insights
• Comprehensive API Coverage: Support for all Klaviyo API endpoints with the latest revision (2024-06-15)
• Performance Optimizations: Intelligent caching, rate limit handling, and efficient data processing
• Robust Error Handling: Fallback mechanisms, detailed logging, and graceful degradation
• Easy Integration: Seamless integration with Claude and other LLMs via the Model Context Protocol

📊 Analytics & Reporting Capabilities

This enhanced version adds powerful analytics capabilities that weren't available in the original:

• Campaign Performance Metrics: Open rates, click rates, bounce rates, and more
• Custom Metric Aggregation: Aggregate metrics by time periods, dimensions, and measurements
• Revenue Attribution: Track revenue generated by campaigns and flows
• Subscriber Insights: Analyze subscriber growth, engagement, and behavior

🔧 Technical Enhancements

1. Centralized Configuration ✅

• Created a central configuration system (src/config.js) for all API parameters
• Made API revision date, valid statistics, and other parameters easily configurable
• Prevented inconsistencies across different files when API parameters change

2. Enhanced Logging System ✅

• Implemented a robust logging system with different log levels (debug, info, warn, error)
• Added specialized logging for API requests and responses
• Masked sensitive data in logs for security
• Configurable log destinations and verbosity

3. Intelligent Rate Limiting ✅

• Added retry logic for rate limit errors
• Implemented exponential backoff with jitter for retries
• Added clear feedback when rate limits are encountered
• Prioritized critical requests during rate limiting

4. Performance Caching ✅

• Implemented in-memory caching for frequently accessed data
• Added cache invalidation based on TTL (time-to-live)
• Optimized cache for different data types (metrics, campaigns, etc.)
• Cache statistics for monitoring and optimization

5. Error Handling & Fallbacks ✅

• Comprehensive error handling for all API interactions
• Fallback mechanisms for degraded operation when primary requests fail
• Detailed error messages and troubleshooting information
• JSON parsing error prevention and handling

🔄 API Version

This enhanced version uses the Klaviyo API Revision 2024-06-15, which includes the latest features and improvements. The server is designed to be forward-compatible with future API revisions through the centralized configuration system.

📋 Attribution

This project is an enhanced version of the original Klaviyo MCP Server created by Matt Coatsworth. The original work provided the foundation for this enhanced version.

🚀 Getting Started

Prerequisites

• Node.js v18 or higher
• A Klaviyo account with API access
• A private API key with appropriate scopes (campaigns:read, metrics:read, etc.)

Installation

1. Clone this repository:

   git clone https://github.com/ivan-rivera-projects/Klaviyo-MCP-Server-Enhanced.git
   cd Klaviyo-MCP-Server-Enhanced
   

2. Install dependencies:

   npm install
   

3. Create a .env file based on .env.example:

   cp .env.example .env
   

4. Edit the .env file to add your Klaviyo API key:

   KLAVIYO_API_KEY=your_private_api_key_here
   LOG_LEVEL=info
   LOG_FILE=/tmp/klaviyo-mcp.log
   LOG_RESPONSES=false
   NODE_ENV=development
   

Starting the Server

Start the server in development mode with automatic reloading:

npm run dev

For production use:

npm start

Testing with MCP Inspector

You can test the server using the MCP Inspector:

npm run inspect

This will open a web interface where you can test all the available tools and resources.

📚 Documentation

For detailed information about the analytics capabilities and API parameters, see:

• ANALYTICS.md - Comprehensive documentation for analytics features and usage
• docs/KLAVIYO_API_REFERENCE.md - Reference for Klaviyo API parameters

🔍 Usage Examples

Getting Campaign Performance Metrics

// Retrieve open rates and click rates for a campaign
get_campaign_metrics({
    id: "01JSQRND0PMH88186NREAJEGGN",
    metrics: ["open_rate", "click_rate", "delivered", "bounce_rate"],
    conversion_metric_id: "VevE7N", // Placed Order metric ID
    start_date: "2025-04-01T00:00:00Z", // Optional: Custom date range
    end_date: "2025-05-01T00:00:00Z"    // Optional: Custom date range
})

Querying Aggregated Metrics

// Count placed orders grouped by month
query_metric_aggregates({
    metric_id: "VevE7N", // Placed Order metric ID
    measurement: "count",
    group_by: ["month"],
    timeframe: "last_30_days", // Predefined timeframe
    // Or use custom dates:
    start_date: "2025-01-01T00:00:00Z",
    end_date: "2025-05-01T00:00:00Z"
})

Getting Campaign Performance Summary

// Get a comprehensive summary of campaign performance
get_campaign_performance({
    id: "01JSQRND0PMH88186NREAJEGGN"
})

🛠️ Available Tools

Analytics & Reporting (New in Enhanced Version)

• get_campaign_metrics: Get performance metrics for a specific campaign (open rates, click rates, etc.)
• query_metric_aggregates: Query aggregated metric data for custom analytics reporting
• get_campaign_performance: Get a comprehensive performance summary for a campaign

Campaigns (Enhanced)

• get_campaigns: Get campaigns from Klaviyo
• get_campaign: Get a specific campaign from Klaviyo
• get_campaign_message: Get a specific campaign message with template details
• get_campaign_messages: Get all messages for a specific campaign
• get_campaign_recipient_estimation: Get estimated recipient count for a campaign

Profiles

• get_profiles: Get profiles from Klaviyo
• get_profile: Get a specific profile from Klaviyo
• create_profile: Create a new profile in Klaviyo
• update_profile: Update an existing profile in Klaviyo
• delete_profile: Delete a profile from Klaviyo

Lists & Segments

• get_lists: Get lists from Klaviyo
• get_list: Get a specific list from Klaviyo
• create_list: Create a new list in Klaviyo
• add_profiles_to_list: Add profiles to a list in Klaviyo
• get_segments: Get segments from Klaviyo
• get_segment: Get a specific segment from Klaviyo

Events & Metrics

• get_events: Get events from Klaviyo
• create_event: Create a new event in Klaviyo
• get_metrics: Get metrics from Klaviyo
• get_metric: Get a specific metric from Klaviyo

Flows

• get_flows: Get flows from Klaviyo
• get_flow: Get a specific flow from Klaviyo
• update_flow_status: Update the status of a flow in Klaviyo

Content Management

• get_templates: Get templates from Klaviyo
• get_template: Get a specific template from Klaviyo
• create_template: Create a new template in Klaviyo
• get_images: Get images from Klaviyo
• get_image: Get a specific image from Klaviyo

E-commerce

• get_catalogs: Get catalogs from Klaviyo
• get_catalog_items: Get items from a catalog in Klaviyo
• get_catalog_item: Get a specific item from a catalog in Klaviyo
• get_coupons: Get coupons from Klaviyo
• create_coupon_code: Create a new coupon code in Klaviyo

Additional Tools

• get_tags: Get tags from Klaviyo
• create_tag: Create a new tag in Klaviyo
• add_tag_to_resource: Add a tag to a resource in Klaviyo
• get_webhooks: Get webhooks from Klaviyo
• create_webhook: Create a new webhook in Klaviyo
• delete_webhook: Delete a webhook from Klaviyo
• request_profile_deletion: Request deletion of a profile for data privacy compliance
• get_forms: Get forms from Klaviyo
• get_form: Get a specific form from Klaviyo
• get_product_reviews: Get product reviews from Klaviyo
• get_product_review: Get a specific product review from Klaviyo

🔗 Available Resources

• klaviyo://profile/{id}: Get information about a specific profile
• klaviyo://list/{id}: Get information about a specific list
• klaviyo://segment/{id}: Get information about a specific segment
• klaviyo://campaign/{id}: Get information about a specific campaign
• klaviyo://flow/{id}: Get information about a specific flow
• klaviyo://template/{id}: Get information about a specific template
• klaviyo://metric/{id}: Get information about a specific metric
• klaviyo://catalog/{id}: Get information about a specific catalog

⚠️ Known Issues and Limitations

• The Klaviyo API may impose rate limits on reporting endpoints
• Some metrics may have a delay before they are available in the API
• Historical data availability may be limited based on your Klaviyo plan
• When using with Claude Desktop, you may occasionally see JSON parsing warnings that don't affect functionality

📝 License

This project is derived from the original Klaviyo MCP Server. Please contact the original author for licensing information.

👥 Contributors

• Original work by Matt Coatsworth
• Enhanced version by Ivan Rivera

🔗 External Resources

• Klaviyo API Documentation
• Model Context Protocol
• Claude Documentation