CleverTap MCP
Read-only AI analytics assistant for CleverTap over the Model Context Protocol. Live public CleverTap APIs only — no mocks, no write endpoints.
Stack
- Bun + TypeScript + Zod
@modelcontextprotocol/sdk(stable, Cursor-fit)@modelcontextprotocol/ext-apps(Claude.ai in-chat chart widgets)- Dual transport: stdio (Cursor) and Streamable HTTP
/mcp(hosted Claude.ai / remote Cursor)
Setup
bun install
cp .env.example .env
# Fill CLEVERTAP_ACCOUNT_ID, CLEVERTAP_PASSCODE, CLEVERTAP_REGION
Regions: in1 | us1 | sg1 | eu1 | aps3 | mec1 | eu
Cursor (local stdio)
Copy .cursor/mcp.json.example to .cursor/mcp.json and set your credentials:
{
"mcpServers": {
"clevertap": {
"command": "bun",
"args": ["run", "D:/clevertap/src/index.ts"],
"env": {
"CLEVERTAP_ACCOUNT_ID": "YOUR_ACCOUNT_ID",
"CLEVERTAP_PASSCODE": "YOUR_PASSCODE",
"CLEVERTAP_REGION": "in1",
"MCP_TRANSPORT": "stdio"
}
}
}
}
Restart Cursor MCP (or reload the window). Tools appear under the CleverTap server. Chart tools return markdown tables in Cursor.
Hosted /mcp (Claude.ai / remote Cursor)
MCP_TRANSPORT=http PORT=3000 bun run src/index.ts
# optional: MCP_AUTH_TOKEN=secret
- MCP endpoint:
http://HOST:3000/mcp - Health:
http://HOST:3000/health
Point Claude.ai custom MCP / remote Cursor at that URL. Same tool surface as stdio. On Claude.ai, tools with _meta.ui.resourceUri render MCP App chart widgets in chat.
Tool groups
| Group | Examples |
|---|---|
| workspace | health_check, account_region, workspace_summary, realtime_dashboard |
| events | event_count, event_trends, compare_events, event_search, … |
| profiles | profile_count, profile_lookup, profiles_by_event, … |
| properties | top_property_values, property_distribution, property_trend, … |
| campaigns | campaign_report, campaign_ctr, campaign_channel_breakdown, … |
| realtime | realtime_active_users, realtime_breakdown, live_dashboard |
| query | run_query, validate_query, query_builder, … |
| metadata | list_events, discover_workspace, schema_summary, … |
| charts | line_chart, bar_chart, pie_chart, table, metric_card, … |
APIs used: /1/counts/events.json, /1/counts/trends.json, /1/counts/top.json, /1/counts/profiles.json, /1/events.json, /1/profiles.json, /1/profile.json, /1/message/report.json, /1/now.json.
Scripts
bun run start # stdio
bun run start:http # HTTP /mcp
bun run typecheck
Notes
- Read-only: no upload, campaign create, or segment write tools.
- Some named tools (e.g.
returning_users,top_events) are honest proxies over public endpoints — they error clearly when CleverTap cannot return the metric. - Internal queue / poll / pagination are shared client helpers, not separate MCP tools.
