moengage-mcp-server 0.1.0

MCP server for MoEngage Campaign APIs - access campaign stats, search campaigns via Model Context Protocol

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)

cd moengage-mcp-server
uv sync

Using pip

cd moengage-mcp-server
pip install -e .

Configuration

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

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):

{
  "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

# 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

# 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

uv sync --all-extras

Run Tests

uv run pytest

Run Linting

uv run ruff check .
uv run mypy src/

Test with MCP Inspector

# 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