README.md•11.8 kB
# Klaviyo MCP Server Enhanced
[](https://smithery.ai/server/@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](https://github.com/mattcoatsworth/Klaviyo-MCP-Server) created by [Matt Coatsworth](https://github.com/mattcoatsworth). 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](docs/STARTUP_ERROR_SUPPRESSION.md).
### Installing via Smithery
To install Klaviyo Enhanced Analytics Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@ivan-rivera-projects/Klaviyo-MCP-Server-Enhanced):
```bash
npx -y @smithery/cli install @ivan-rivera-projects/Klaviyo-MCP-Server-Enhanced --client claude
```
### Installation
1. Clone this repository:
```bash
git clone https://github.com/ivan-rivera-projects/Klaviyo-MCP-Server-Enhanced.git
cd Klaviyo-MCP-Server-Enhanced
```
2. Install dependencies:
```bash
npm install
```
3. Create a `.env` file based on `.env.example`:
```bash
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:
```bash
npm run dev
```
For production use:
```bash
npm start
```
### Testing with MCP Inspector
You can test the server using the MCP Inspector:
```bash
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](ANALYTICS.md) - Comprehensive documentation for analytics features and usage
- [docs/KLAVIYO_API_REFERENCE.md](docs/KLAVIYO_API_REFERENCE.md) - Reference for Klaviyo API parameters
## 🔍 Usage Examples
### Getting Campaign Performance Metrics
```javascript
// 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
```javascript
// 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
```javascript
// 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](https://github.com/mattcoatsworth)
- Enhanced version by [Ivan Rivera](https://github.com/ivan-rivera-projects)
## 🔗 External Resources
- [Klaviyo API Documentation](https://developers.klaviyo.com/en/reference/api_overview)
- [Model Context Protocol](https://github.com/anthropics/anthropic-cookbook/tree/main/mcp)
- [Claude Documentation](https://docs.anthropic.com/claude/)