relay-commerce/Klaviyo-MCP-Server

Klaviyo MCP Server

A comprehensive Model Context Protocol (MCP) server that provides complete access to Klaviyo's API functionality. This server enables AI assistants like Claude to interact with all major Klaviyo APIs through 34+ tools covering profiles, campaigns, flows, lists, segments, events, and more.

🚀 Features

Complete API Coverage

• Profiles API (4 tools) - Create, read, update, search customer profiles
• Lists API (4 tools) - Manage lists and list memberships
• Campaigns API (4 tools) - Create, manage, and send email campaigns
• Segments API (3 tools) - Create and query dynamic customer segments
• Events API (3 tools) - Track and retrieve customer events
• Flows API (3 tools) - Manage automated email flows
• Metrics API (2 tools) - Access performance metrics
• Templates API (2 tools) - Manage email templates
• Catalogs API (3 tools) - Manage product catalogs and variants
• Coupons API (2 tools) - Create and manage discount coupons
• Reporting API (2 tools) - Query campaign and flow analytics
• Accounts API (2 tools) - Access account information

Key Features

• ✅ 34 tools covering all major Klaviyo API endpoints
• ✅ Secure authentication using Klaviyo private API keys
• ✅ Comprehensive error handling for network, HTTP, and API errors
• ✅ Rate limiting protection with timeout and retry logic
• ✅ Input validation for all parameters and JSON data
• ✅ Consistent interface - all tools follow the same patterns
• ✅ JSON:API format support with filtering, pagination, and sorting
• ✅ Complete documentation with usage examples

📋 Prerequisites

• Python 3.10 or higher
• Klaviyo account with API access
• Klaviyo Private API Key (Get yours here)

🛠️ Installation

Quick Setup

1. Clone the repository:

   git clone https://github.com/relay-commerce/Klaviyo-MCP-Server.git
   cd Klaviyo-MCP-Server
   

2. Run the setup script:

   chmod +x klaviyo_setup.sh
   ./klaviyo_setup.sh
   

3. Get your Klaviyo API key:

   • Go to Klaviyo API Keys
   • Create a new private API key with appropriate scopes

Manual Setup

1. Create virtual environment:

   python3 -m venv klaviyo_mcp_env
   source klaviyo_mcp_env/bin/activate
   

2. Install dependencies:

   pip install -r klaviyo_requirements.txt
   

🧪 Testing

Test the server to ensure everything is working:

source klaviyo_mcp_env/bin/activate
python test_klaviyo_server.py

You should see output confirming all 34 tools are available:

✅ SUCCESS: All expected tools are available!
Test completed. Total tools available: 34

🔧 Usage

With Claude Desktop

Add the server to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "klaviyo": {
      "command": "python",
      "args": ["/absolute/path/to/klaviyo_mcp_server.py"]
    }
  }
}

With MCP CLI

# List available tools
mcp-cli tool list --server klaviyo

# Call a specific tool
mcp-cli tool call get_profiles --server klaviyo --input '{"api_key": "your-api-key"}'

📖 API Examples

Create a Customer Profile

create_profile(
    api_key="your-api-key",
    profile_data='{"email": "customer@example.com", "first_name": "John", "last_name": "Doe"}'
)

Get All Campaigns

get_campaigns(
    api_key="your-api-key",
    filter_expr="equals(status,'draft')",
    page_size=50
)

Track a Custom Event

create_event(
    api_key="your-api-key",
    event_data='{"metric": {"name": "Placed Order"}, "profile": {"email": "customer@example.com"}, "properties": {"value": 99.99, "item_count": 2}}'
)

Create a Customer Segment

create_segment(
    api_key="your-api-key",
    segment_data='{"name": "High Value Customers", "definition": {"condition_groups": [{"conditions": [{"field": "properties.total_spent", "operator": "greater-than", "value": 1000}]}]}}'
)

Send a Campaign

send_campaign(
    api_key="your-api-key",
    campaign_id="campaign-id-here"
)

🔐 Authentication

The server uses Klaviyo Private API Keys for authentication. Each tool requires an api_key parameter:

• Never hardcode API keys in your code
• Pass API keys as parameters to each tool call
• Ensure your API key has the necessary scopes for the operations you want to perform

Required API Scopes

Make sure your Klaviyo API key has these scopes:

• profiles:read, profiles:write
• lists:read, lists:write
• campaigns:read, campaigns:write
• segments:read, segments:write
• events:read, events:write
• flows:read, flows:write
• metrics:read
• templates:read, templates:write
• catalogs:read, catalogs:write
• coupons:read, coupons:write

📊 Available Tools

⚡ Rate Limits

Klaviyo has the following rate limits:

• Burst: 75 requests per second
• Steady: 700 requests per minute

The server includes built-in protection with timeout handling and proper error messages for rate limit scenarios.

🛡️ Security

• ✅ API keys are passed as parameters (never hardcoded)
• ✅ All requests use HTTPS
• ✅ Proper error handling prevents sensitive data exposure
• ✅ Input validation for all parameters
• ✅ No secrets stored in code or logs

🔧 Technical Details

• API Base URL: https://a.klaviyo.com/api
• API Revision: 2025-04-15
• Protocol: JSON:API format
• Authentication: Klaviyo-API-Key header
• Python Version: 3.10+
• MCP Version: 1.0.0+

📁 File Structure

Klaviyo-MCP-Server/
├── klaviyo_mcp_server.py      # Main MCP server implementation
├── klaviyo_requirements.txt   # Python dependencies
├── klaviyo_setup.sh          # Setup script
├── klaviyo_documentation.md  # Detailed documentation
├── test_klaviyo_server.py    # Test script
└── README.md                 # This file

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the file for details.

🆘 Support

• Issues: GitHub Issues
• Klaviyo API Docs: Klaviyo Developer Portal
• MCP Documentation: Model Context Protocol

🏆 Why This MCP Server?

This is the most comprehensive Klaviyo MCP integration available, providing:

• ✅ Complete API coverage - All major Klaviyo endpoints
• ✅ Production ready - Proper error handling and security
• ✅ Easy to use - Consistent interface across all tools
• ✅ Well documented - Clear examples and setup instructions
• ✅ Actively maintained - Regular updates and improvements

Perfect for businesses wanting to integrate Klaviyo functionality into AI-powered workflows, customer service automation, marketing automation, and data analysis tasks.

Made with ❤️ for the Klaviyo and MCP communities