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 STARTUP_ERROR_SUPPRESSION.md.
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
.envfile based on.env.example:cp .env.example .env -
Edit the
.envfile 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 reportingget_campaign_performance: Get a comprehensive performance summary for a campaign
Campaigns (Enhanced)
get_campaigns: Get campaigns from Klaviyoget_campaign: Get a specific campaign from Klaviyoget_campaign_message: Get a specific campaign message with template detailsget_campaign_messages: Get all messages for a specific campaignget_campaign_recipient_estimation: Get estimated recipient count for a campaign
Profiles
get_profiles: Get profiles from Klaviyoget_profile: Get a specific profile from Klaviyocreate_profile: Create a new profile in Klaviyoupdate_profile: Update an existing profile in Klaviyodelete_profile: Delete a profile from Klaviyo
Lists & Segments
get_lists: Get lists from Klaviyoget_list: Get a specific list from Klaviyocreate_list: Create a new list in Klaviyoadd_profiles_to_list: Add profiles to a list in Klaviyoget_segments: Get segments from Klaviyoget_segment: Get a specific segment from Klaviyo
Events & Metrics
get_events: Get events from Klaviyocreate_event: Create a new event in Klaviyoget_metrics: Get metrics from Klaviyoget_metric: Get a specific metric from Klaviyo
Flows
get_flows: Get flows from Klaviyoget_flow: Get a specific flow from Klaviyoupdate_flow_status: Update the status of a flow in Klaviyo
Content Management
get_templates: Get templates from Klaviyoget_template: Get a specific template from Klaviyocreate_template: Create a new template in Klaviyoget_images: Get images from Klaviyoget_image: Get a specific image from Klaviyo
E-commerce
get_catalogs: Get catalogs from Klaviyoget_catalog_items: Get items from a catalog in Klaviyoget_catalog_item: Get a specific item from a catalog in Klaviyoget_coupons: Get coupons from Klaviyocreate_coupon_code: Create a new coupon code in Klaviyo
Additional Tools
get_tags: Get tags from Klaviyocreate_tag: Create a new tag in Klaviyoadd_tag_to_resource: Add a tag to a resource in Klaviyoget_webhooks: Get webhooks from Klaviyocreate_webhook: Create a new webhook in Klaviyodelete_webhook: Delete a webhook from Klaviyorequest_profile_deletion: Request deletion of a profile for data privacy complianceget_forms: Get forms from Klaviyoget_form: Get a specific form from Klaviyoget_product_reviews: Get product reviews from Klaviyoget_product_review: Get a specific product review from Klaviyo
🔗 Available Resources
klaviyo://profile/{id}: Get information about a specific profileklaviyo://list/{id}: Get information about a specific listklaviyo://segment/{id}: Get information about a specific segmentklaviyo://campaign/{id}: Get information about a specific campaignklaviyo://flow/{id}: Get information about a specific flowklaviyo://template/{id}: Get information about a specific templateklaviyo://metric/{id}: Get information about a specific metricklaviyo://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