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

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