Content
# 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 |
| `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 |
### 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_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
