# MoEngage MCP Server

**Access MoEngage Campaign APIs through the Model Context Protocol (MCP)**

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![PyPI version](https://badge.fury.io/py/moengage-mcp-server.svg)](https://pypi.org/project/moengage-mcp-server/)

---

## Overview

MoEngage MCP Server is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that enables AI assistants like Claude to interact with MoEngage Campaign APIs. Query campaign statistics, search campaigns, and analyze marketing performance using natural language.

## Features

- **Campaign Statistics** - Fetch detailed performance metrics including delivery rates, CTR, impressions, and more
- **Email Campaigns** - Search and retrieve email campaign configurations and content
- **Push Notifications** - Access push notification campaign details across platforms
- **SMS Campaigns** - Retrieve SMS campaign information and connector details
- **Multi Data Center Support** - Works with all MoEngage data centers (DC01-DC06)
- **Secure by Design** - Credentials are masked in logs, environment-based configuration

## Installation

### Quick Install (Recommended)

```bash
uvx moengage-mcp-server@latest
```

### Install with pip

```bash
pip install moengage-mcp-server
```

### Install from Source

```bash
git clone https://github.com/moengage/moengage-mcp-server.git
cd moengage-mcp-server
uv sync
```

## Configuration

### Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `MOENGAGE_WORKSPACE_ID` | Yes | - | Your MoEngage Workspace ID |
| `MOENGAGE_CAMPAIGN_REPORTS_API_KEY` | Yes | - | Campaign Reports API Key |
| `MOENGAGE_DATA_CENTER` | No | `01` | Data center code (01-06) |
| `MOENGAGE_TIMEOUT` | No | `30` | API timeout in seconds |
| `MOENGAGE_MAX_RETRIES` | No | `3` | Max retry attempts |

### Finding Your Credentials

1. Log in to [MoEngage Dashboard](https://dashboard.moengage.com)
2. Navigate to **Settings** → **Account** → **APIs**
3. Copy your **Workspace ID** and **Campaign Reports API Key**
4. Check your dashboard URL to determine your data center (e.g., `dashboard-02.moengage.com` → DC02)

## Quick Start

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "moengage": {
      "command": "uvx",
      "args": ["moengage-mcp-server@latest"],
      "env": {
        "MOENGAGE_WORKSPACE_ID": "your-workspace-id",
        "MOENGAGE_CAMPAIGN_REPORTS_API_KEY": "your-api-key",
        "MOENGAGE_DATA_CENTER": "01"
      }
    }
  }
}
```

### Claude Code

Add to `~/.claude/settings.json`:

```json
{
  "mcpServers": {
    "moengage": {
      "type": "stdio",
      "command": "uvx",
      "args": ["moengage-mcp-server@latest"],
      "env": {
        "MOENGAGE_WORKSPACE_ID": "your-workspace-id",
        "MOENGAGE_CAMPAIGN_REPORTS_API_KEY": "your-api-key",
        "MOENGAGE_DATA_CENTER": "01"
      }
    }
  }
}
```

### VS Code

Add to `.vscode/settings.json`:

```json
{
  "mcp.servers": {
    "moengage": {
      "command": "uvx",
      "args": ["moengage-mcp-server@latest"],
      "env": {
        "MOENGAGE_WORKSPACE_ID": "your-workspace-id",
        "MOENGAGE_CAMPAIGN_REPORTS_API_KEY": "your-api-key",
        "MOENGAGE_DATA_CENTER": "01"
      }
    }
  }
}
```

## Available Tools

### `get_campaign_stats`

Fetch performance statistics for one or more campaigns.

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `campaign_ids` | list | Yes | List of campaign IDs (max 50) |
| `start_date` | string | Yes | Start date (YYYY-MM-DD) |
| `end_date` | string | Yes | End date (YYYY-MM-DD) |
| `attribution_type` | string | No | `VIEW_THROUGH` or `CLICK_THROUGH` (default: `VIEW_THROUGH`) |
| `metric_type` | string | No | `TOTAL` or `UNIQUE` (default: `TOTAL`) |

**Metrics Returned:**
- `attempted` - Total messages attempted
- `sent` - Successfully sent messages
- `failed` - Failed messages
- `impression` - Total impressions/opens
- `click` - Total clicks
- `ctr` - Click-through rate (%)
- `delivery_rate` - Delivery rate (%)
- `sent_rate` - Sent rate (%)
- `failure_rate` - Failure rate (%)

### `get_email_campaigns`

Search and retrieve email campaign details.

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `campaign_id` | string | No | Specific campaign ID to fetch |
| `campaign_name` | string | No | Filter by campaign name |
| `status` | string | No | Filter by status |
| `limit` | integer | No | Results per page (1-15, default: 10) |
| `page` | integer | No | Page number (default: 1) |
| `include_archived` | boolean | No | Include archived campaigns (default: false) |

**Status Values:** `DRAFT`, `SCHEDULED`, `ACTIVE`, `PAUSED`, `COMPLETED`, `STOPPED`

### `get_push_campaigns`

Search and retrieve push notification campaign details.

**Parameters:** Same as `get_email_campaigns`

### `get_sms_campaigns`

Search and retrieve SMS campaign details.

**Parameters:** Same as `get_email_campaigns`

## Data Centers

| Code | API Endpoint | Dashboard URL |
|------|--------------|---------------|
| `01` | `api-01.moengage.com` | `dashboard.moengage.com` |
| `02` | `api-02.moengage.com` | `dashboard-02.moengage.com` |
| `03` | `api-03.moengage.com` | `dashboard-03.moengage.com` |
| `04` | `api-04.moengage.com` | `dashboard-04.moengage.com` |
| `05` | `api-05.moengage.com` | `dashboard-05.moengage.com` |
| `06` | `api-06.moengage.com` | `dashboard-06.moengage.com` |

## Usage Examples

Once configured, you can use natural language with Claude:

```
Get the performance stats for campaign abc123 for the last 30 days
```

```
Show me all active email campaigns
```

```
Compare the CTR of campaigns abc123 and def456 for December 2024
```

```
Find SMS campaigns with "welcome" in the name
```

## Development

### Setup

```bash
git clone https://github.com/moengage/moengage-mcp-server.git
cd moengage-mcp-server
uv sync --extra dev
```

### Running Tests

```bash
uv run pytest
```

### Code Quality

```bash
# Linting
uv run ruff check .

# Type checking
uv run mypy src/
```

### Building

```bash
uv build
```

## Project Structure

```
moengage-mcp-server/
├── src/
│   └── moengage_mcp/
│       ├── __init__.py      # Package initialization
│       ├── config.py        # Configuration management
│       ├── models.py        # Pydantic models
│       ├── client.py        # HTTP client for MoEngage API
│       └── server.py        # MCP server implementation
├── tests/                   # Test files
├── docs/                    # Documentation (MkDocs)
├── .env.example            # Environment template
├── pyproject.toml          # Project configuration
└── README.md               # This file
```

## Security

- **Environment Variables** - Credentials are never hardcoded
- **Credential Masking** - API keys are automatically masked in logs
- **Secure Transport** - All API calls use HTTPS

## Troubleshooting

### Authentication Errors

- Verify your Workspace ID and API Key are correct
- Ensure your API key has Campaign Reports permissions
- Check your data center setting matches your account

### Connection Timeout

- Check your internet connection
- Try increasing `MOENGAGE_TIMEOUT` value
- Verify the MoEngage API is accessible from your network

### No Data Returned

- Verify the campaign IDs exist in your account
- Check the date range includes campaign activity
- Ensure your API key has access to the requested campaigns

## Support

- [GitHub Issues](https://github.com/moengage/moengage-mcp-server/issues) - Bug reports and feature requests
- [MoEngage Documentation](https://developers.moengage.com) - Official MoEngage API docs
- [MCP Specification](https://modelcontextprotocol.io) - Model Context Protocol documentation
