The Klaviyo MCP Server is a comprehensive tool for interacting with the Klaviyo API, offering advanced analytics and seamless integration capabilities.
- Profile Management: Create, read, update, and delete profiles with detailed properties
- Lists & Segments: Manage customer lists and access segment data
- Events & Metrics: Track events and retrieve detailed analytics with filtering options
- Campaign Management: Access performance metrics, messages, and recipient estimations
- Flow Management: Control marketing automation flows and update their status
- Content Management: Create and manage email templates and images
- E-commerce Integration: Manage catalogs, items, coupons, and coupon codes
- Additional Resources: Handle tags, webhooks, forms, and product reviews
- Performance Features: Includes caching, intelligent rate limiting, and robust error handling
Used for managing environment variables, specifically storing the Klaviyo API key securely in a .env file for authentication.
Used for package management, installing dependencies, and running scripts for the MCP server including development and testing modes.
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:
Installation
- Clone this repository:
- Install dependencies:
- Create a
.env
file based on.env.example
: - Edit the
.env
file to add your Klaviyo API key:
Starting the Server
Start the server in development mode with automatic reloading:
For production use:
Testing with MCP Inspector
You can test the server using the MCP Inspector:
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
Querying Aggregated Metrics
Getting Campaign Performance Summary
🛠️ 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
🔗 External Resources
You must be authenticated.
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Tools
A comprehensive Model Context Protocol server that enables interaction with the Klaviyo API, providing tools and resources for managing customer profiles, lists, segments, campaigns, flows, and various marketing automation features.
Related MCP Servers
- -securityAlicense-qualityA Model Context Protocol server that enables Claude to interact with the ConnectWise Manage API to perform operations like retrieving, creating, updating, and deleting tickets, companies, contacts, and other entities.Last updated -JavaScriptMIT License
- -securityAlicense-qualityA Model Context Protocol server that provides seamless interaction with Workato's API through custom AI tools, enabling management of recipes, connections, connectors, folders, and activity logs.Last updated -TypeScriptMIT License
- -securityFlicense-qualityA Model Context Protocol server that provides a comprehensive interface for interacting with the ConnectWise Manage API, simplifying API discovery, execution, and management for both developers and AI assistants.Last updated -462Python
- -securityAlicense-qualityA Model Context Protocol server that provides standardized interfaces for interacting with Ollama API, offering JSON responses, error handling, and intelligent guidance for LLM-based API calls.Last updated -PythonMIT License