# 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](https://www.klaviyo.com/account#api-keys-tab))

## 🛠️ Installation

### Quick Setup

1. **Clone the repository**:
   ```bash
   git clone https://github.com/relay-commerce/Klaviyo-MCP-Server.git
   cd Klaviyo-MCP-Server
   ```

2. **Run the setup script**:
   ```bash
   chmod +x klaviyo_setup.sh
   ./klaviyo_setup.sh
   ```

3. **Get your Klaviyo API key**:
   - Go to [Klaviyo API Keys](https://www.klaviyo.com/account#api-keys-tab)
   - Create a new private API key with appropriate scopes

### Manual Setup

1. **Create virtual environment**:
   ```bash
   python3 -m venv klaviyo_mcp_env
   source klaviyo_mcp_env/bin/activate
   ```

2. **Install dependencies**:
   ```bash
   pip install -r klaviyo_requirements.txt
   ```

## 🧪 Testing

Test the server to ensure everything is working:

```bash
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`

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

### With MCP CLI

```bash
# 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
```python
create_profile(
    api_key="your-api-key",
    profile_data='{"email": "customer@example.com", "first_name": "John", "last_name": "Doe"}'
)
```

### Get All Campaigns
```python
get_campaigns(
    api_key="your-api-key",
    filter_expr="equals(status,'draft')",
    page_size=50
)
```

### Track a Custom Event
```python
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
```python
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
```python
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

<details>
<summary><strong>Profiles API (4 tools)</strong></summary>

- `get_profiles()` - List all profiles with filtering, pagination, and sorting
- `create_profile()` - Create new customer profiles
- `get_profile()` - Get specific profile by ID
- `update_profile()` - Update existing profile data
</details>

<details>
<summary><strong>Lists API (4 tools)</strong></summary>

- `get_lists()` - List all lists in account
- `create_list()` - Create new lists
- `get_list_profiles()` - Get profiles in a specific list
- `add_profiles_to_list()` - Add profiles to lists
</details>

<details>
<summary><strong>Campaigns API (4 tools)</strong></summary>

- `get_campaigns()` - List all campaigns
- `create_campaign()` - Create new email campaigns
- `get_campaign()` - Get specific campaign details
- `send_campaign()` - Send campaigns immediately
</details>

<details>
<summary><strong>Segments API (3 tools)</strong></summary>

- `get_segments()` - List all segments
- `create_segment()` - Create new dynamic segments
- `get_segment_profiles()` - Get profiles in segments
</details>

<details>
<summary><strong>Events API (3 tools)</strong></summary>

- `get_events()` - List events with filtering and sorting
- `create_event()` - Track new customer events
- `get_event()` - Get specific event details
</details>

<details>
<summary><strong>Flows API (3 tools)</strong></summary>

- `get_flows()` - List all automated flows
- `get_flow()` - Get specific flow details
- `update_flow_status()` - Update flow status (draft/live/stopped/archived)
</details>

<details>
<summary><strong>Other APIs</strong></summary>

**Metrics API (2 tools)**
- `get_metrics()` - List all available metrics
- `get_metric()` - Get specific metric details

**Templates API (2 tools)**
- `get_templates()` - List all email templates
- `create_template()` - Create new email templates

**Catalogs API (3 tools)**
- `get_catalog_items()` - List catalog items
- `create_catalog_item()` - Create new catalog items
- `get_catalog_variants()` - List catalog variants

**Coupons API (2 tools)**
- `get_coupons()` - List all coupons
- `create_coupon()` - Create new coupons

**Reporting API (2 tools)**
- `query_campaign_values()` - Get campaign performance metrics
- `query_flow_values()` - Get flow performance metrics

**Accounts API (2 tools)**
- `get_accounts()` - Get account information
- `get_account()` - Get specific account details
</details>

## ⚡ 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 [LICENSE](LICENSE) file for details.

## 🆘 Support

- **Issues**: [GitHub Issues](https://github.com/relay-commerce/Klaviyo-MCP-Server/issues)
- **Klaviyo API Docs**: [Klaviyo Developer Portal](https://developers.klaviyo.com/)
- **MCP Documentation**: [Model Context Protocol](https://modelcontextprotocol.io/)

## 🏆 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**