# moengage-mcp

A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for the
[MoEngage](https://www.moengage.com) marketing platform. Exposes campaign and
email-template tools over stdio, built on [FastMCP](https://github.com/jlowin/fastmcp).

Unlike MoEngage's official MCP (analytics-oriented, interactive OAuth), this server
uses the documented [Campaign/Content API](https://www.moengage.com/docs/api/introduction)
with plain API-key auth — it runs headless, and it reads **campaign targeting**
(the full `segmentation_details` filter tree via `search_campaigns`), which the
official server does not expose.

## Tools

### Campaigns (9)

| Tool | Mutates | Purpose |
|---|---|---|
| `search_campaigns` | no | Search/filter campaigns; returns config **including the full targeting filter tree** (`segmentation_details`). Email `html_content` is replaced with a byte count unless `include_content=true` |
| `get_campaign_meta` | no | Thin identity view: status, channel, delivery type, team, tags, dates (no targeting) |
| `get_child_executions` | no | Individual runs of a recurring (periodic) campaign |
| `get_personalized_preview` | no | Render campaign content with placeholders resolved for sample attributes |
| `get_campaign_stats` | no | ⚠ Disabled upstream — hidden unless `MOENGAGE_ENABLE_STATS=true`; re-enable when MoEngage turns the endpoint back on |
| `create_campaign` | **yes** | Create a campaign; auto-supplies required `delivery_controls`/`advanced` for triggered types, strips the empty-`intelligent_delay_optimization` validator trap, `create_paused=true` pauses right after creation (API campaigns land Scheduled, not draft) |
| `update_campaign` | **yes** | Update campaign config |
| `change_campaign_status` | **yes** | Activate / pause / stop a campaign |
| `test_campaign` | **yes** | Send a real test push/email to named recipients |

### Custom segments (3)

| Tool | Mutates | Purpose |
|---|---|---|
| `create_custom_segment` | **yes** | Create a filter segment — event shortcut ("executed X ≥N times in last D days") or full filter tree. Segment user counts are dashboard-only (no API exposes them) |
| `get_custom_segment` | no | Get one segment's definition by id, or list all custom segments |
| `archive_custom_segment` | **yes** | Archive (deferred delete, ~30d purge) or restore a segment |

### Email templates (9)

| Tool | Mutates | Purpose |
|---|---|---|
| `search_templates` | no | Search templates with filters and pagination |
| `analyze_template` | no | Parse template HTML into structured content nodes |
| `compare_templates` | no | Structured diff of two templates |
| `build_email_template` | no | Build + validate a template, return a structured preview (no publish); `autofix=true` repairs mechanical layout issues (isolation spacers, missing disclaimer/footer) |
| `get_server_info` | no | Data center + dashboard base URL |
| `publish_template` | **yes** | Build + validate + publish to MoEngage |
| `update_template` | **yes** | Update an existing template |
| `localize_template` | **yes** | Publish a translated market variant |
| `patch_template_text` | **yes** | Modify specific text nodes without a rebuild |

Tools return structured previews, never raw HTML — large payloads would
overflow an agent's context window.

**Gating writes:** the server ships all tools; restrict the mutating ones in
your MCP client (e.g. Claude Code `permissions.allow` listing only the read
tools). Read and write tools share MoEngage's campaign-API rate limits
(5/min, 25/hr, 100/day) — avoid fanning out calls.

## Install & run

```bash
pip install git+https://github.com/poddubnyoleg/moengage_mcp.git
moengage-mcp            # stdio
```

Claude Code / Claude Desktop config:

```json
{
  "mcpServers": {
    "moengage": {
      "type": "stdio",
      "command": "moengage-mcp"
    }
  }
}
```

## Configuration

Environment variables (or a local `.env`, see `.env.example`):

| Variable | Required | Description |
|---|---|---|
| `MOENGAGE_API_KEY` | yes | Campaign/Content API key (dashboard → Settings → APIs) |
| `MOENGAGE_DATA_API_KEY` | for segments | Data API key (dashboard → Settings → APIs → Data) — the segment tools authenticate against MoEngage's Data API family, which rejects the campaign key with a 401 `APP_SECRET key mismatch`. Falls back to `MOENGAGE_API_KEY` |
| `MOENGAGE_WORKSPACE_ID` | yes | Workspace (app) ID |
| `MOENGAGE_DATA_CENTER` | yes | Regional DC, e.g. `02` for `dashboard-02.moengage.com` |
| `MOENGAGE_FOOTER_CONFIG` | no | Brand links for the email footer component — inline JSON or a file path (schema in `footer.py`); without it the footer carries only an Unsubscribe link |
| `MOENGAGE_ENABLE_STATS` | no | Set `true` to register `get_campaign_stats` (hidden by default while the upstream endpoint is disabled) |

API errors (including 401 on rotated keys) come back as structured error dicts,
so a consuming agent can report them instead of failing opaquely.

## Notes

- `content/email/TEMPLATE_GUIDELINES.md` documents an example house style the
  template validator enforces (component order, CTA compliance, Jinja rules) —
  adapt to your brand.
- Audience reachability counts are only returned by MoEngage for one-time
  scheduled campaigns, not periodic ones.

## License

MIT