README - Klaviyo MCP Server Enhanced by ivan-rivera-projects

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
Advanced JSON parsing error prevention and handling
Intelligent buffer management to recover from corrupted messages
Automatic sanitization of malformed JSON inputs
Suppression of error popups for better user experience

🔄 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.)

⚠️ Important Note About Startup Warnings

When you first start Claude Desktop with this MCP tool, you will see several JSON parsing error notifications appear. This is normal and expected behavior.

These warnings occur during the initial connection phase between Claude and the MCP server and do not affect the functionality of the tool. Once Claude is fully initialized, these warnings will stop appearing, and the tool will work normally.

Key points to remember:

These warnings are harmless and can be safely dismissed
They only appear during startup and not during normal operation
The MCP server is still functioning correctly despite these warnings
All analytics and API features will work as expected

For more technical details about these warnings, see .

Installing via Smithery

To install Klaviyo Enhanced Analytics Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @ivan-rivera-projects/Klaviyo-MCP-Server-Enhanced --client claude

Installation

Clone this repository:

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

Install dependencies:
```
npm install
```
Create a .env file based on .env.example:
```
cp .env.example .env
```

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:

- Comprehensive documentation for analytics features and usage
- 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 starting Claude Desktop, you will see JSON parsing warnings. These are expected and don't affect functionality (see "Important Note About Startup Warnings" section above)

📝 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