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 ACCOUNT_API_KEY (format: accountId: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": {
        "ACCOUNT_API_KEY": "YOUR_ACCOUNT_ID: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, …
insights (CQL gap-closure)	revenue_trend, opt_out_rate, segment_membership, os_split, campaign_delivery_report, campaign_goal_conversion, campaign_revenue, frequency_analysis, uninstall_health_check
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.

Capability report

Full analysis of what this MCP can and cannot pull from CleverTap (tools, schemas, APIs, gaps):

• docs/MCP_REPORT.md