Metadata-Version: 2.4
Name: moengage-mcp-server
Version: 0.1.0
Summary: MCP server for MoEngage Campaign APIs - access campaign stats, search campaigns via Model Context Protocol
Project-URL: Homepage, https://github.com/moengage/moengage-mcp-server
Project-URL: Documentation, https://developers.moengage.com
Project-URL: Repository, https://github.com/moengage/moengage-mcp-server
Project-URL: Issues, https://github.com/moengage/moengage-mcp-server/issues
Author-email: MoEngage <support@moengage.com>
License: MIT
Keywords: ai,analytics,campaigns,claude,llm,marketing,mcp,model-context-protocol,moengage
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp[cli]>=1.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# MoEngage MCP Server

A production-grade Model Context Protocol (MCP) server for the MoEngage Stats API. This server enables LLMs like Claude to fetch and analyze MoEngage campaign statistics.

## Features

- **Stats API Integration**: Fetch campaign performance metrics including delivery, engagement, and rate statistics
- **Multi-Datacenter Support**: Works with all MoEngage data centers (DC01-DC06)
- **Production Ready**: Includes retry logic, error handling, connection pooling, and structured logging
- **Type Safe**: Full Pydantic validation for requests and responses
- **Multiple Transports**: Supports stdio (local), HTTP, and SSE transports

## Installation

### Using uv (Recommended)

```bash
cd moengage-mcp-server
uv sync
```

### Using pip

```bash
cd moengage-mcp-server
pip install -e .
```

## Configuration

Create a `.env` file in the project root (or set environment variables):

```bash
cp .env.example .env
# Edit .env with your MoEngage credentials
```

### Required Environment Variables

| Variable | Description |
|----------|-------------|
| `MOENGAGE_WORKSPACE_ID` | Your MoEngage Workspace ID (found in Settings > Account > APIs) |
| `MOENGAGE_API_KEY` | Your MoEngage API Key for Campaign Reports |

### Optional Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `MOENGAGE_DATA_CENTER` | `01` | Data center (01-06) |
| `MOENGAGE_TIMEOUT` | `30` | API request timeout in seconds |
| `MOENGAGE_MAX_RETRIES` | `3` | Max retry attempts |
| `LOG_LEVEL` | `INFO` | Logging level |

### Finding Your Data Center

Check your MoEngage dashboard URL:
- `dashboard-01.moengage.com` → DC01
- `dashboard-02.moengage.com` → DC02
- etc.

## Usage

### With Claude Desktop

Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "moengage": {
      "command": "uv",
      "args": ["--directory", "/path/to/moengage-mcp-server", "run", "moengage-mcp"],
      "env": {
        "MOENGAGE_WORKSPACE_ID": "your_workspace_id",
        "MOENGAGE_API_KEY": "your_api_key",
        "MOENGAGE_DATA_CENTER": "01"
      }
    }
  }
}
```

### With Claude Code CLI

```bash
# Add the server
claude mcp add moengage -- uv --directory /path/to/moengage-mcp-server run moengage-mcp

# Or with HTTP transport
claude mcp add --transport http moengage http://localhost:8000/mcp
```

### Standalone HTTP Server

```bash
# Start the server
moengage-mcp --transport http --port 8000

# Or with uv
uv run moengage-mcp --transport http --port 8000
```

## Available Tools

### get_campaign_stats

Fetch campaign statistics from the MoEngage Stats API.

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `campaign_ids` | list[str] | Yes | List of campaign IDs (max 50) |
| `start_date` | str | Yes | Start date (YYYY-MM-DD) |
| `end_date` | str | Yes | End date (YYYY-MM-DD) |
| `attribution_type` | str | No | `VIEW_THROUGH` or `CLICK_THROUGH` (default: `VIEW_THROUGH`) |
| `metric_type` | str | No | `TOTAL` or `UNIQUE` (default: `TOTAL`) |
| `request_id` | str | No | Request ID for tracking |

**Example:**

```
Use the get_campaign_stats tool to fetch stats for campaign "abc123"
from 2024-12-01 to 2024-12-31
```

**Response includes:**
- Delivery metrics: attempted, sent, failed
- Engagement metrics: impressions, clicks, CTR
- Rate metrics: delivery_rate, sent_rate, failure_rate
- Variation-level breakdowns
- Control group statistics

## Available Resources

### moengage://config

Returns current server configuration (non-sensitive) including:
- Configured data center
- API endpoints
- Timeout and retry settings

## Available Prompts

### analyze_campaign_performance

Generates a prompt for comprehensive campaign analysis including:
- Delivery performance analysis
- Engagement metrics insights
- Optimization recommendations

## Rate Limits

The MoEngage Stats API has a rate limit of **100 API calls per minute per workspace**. The server tracks and reports remaining rate limit in responses.

## Error Handling

The server handles various error scenarios:

| Error | Handling |
|-------|----------|
| Rate Limit (429) | Returns error with `retry_after` seconds |
| Authentication (401/403) | Returns clear credential error message |
| Network Errors | Automatic retry with exponential backoff |
| Validation Errors | Returns structured error with details |

## Development

### Setup Development Environment

```bash
uv sync --all-extras
```

### Run Tests

```bash
uv run pytest
```

### Run Linting

```bash
uv run ruff check .
uv run mypy src/
```

### Test with MCP Inspector

```bash
# Start the server
uv run moengage-mcp --transport http --port 8000

# In another terminal, run the inspector
npx -y @modelcontextprotocol/inspector
# Connect to http://localhost:8000/mcp
```

## 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
├── .env.example            # Environment template
├── pyproject.toml          # Project configuration
└── README.md               # This file
```

## License

MIT License
