clevertap-mcp

一个用于 CleverTap REST API 的模型上下文协议 (MCP) 服务器。它将 CleverTap 的用户画像、事件、营销活动和报告作为工具公开，任何兼容 MCP 的 AI 助手（如 Claude、Cursor 等）都可以直接调用。

功能特性

多项目支持 — 从单个服务器实例管理多个 CleverTap 账户
引导式设置 — 如果未配置项目，clevertap_configure 将引导您完成整个过程
全面的 API 覆盖 — 支持事件、画像、营销活动和报告
异步轮询 — 自动轮询长时间运行的操作（事件/画像计数）

工具

元数据

工具	描述
`clevertap_configure`	引导式设置，用于添加项目或生成 `CLEVERTAP_PROJECTS` 配置
`clevertap_list_projects`	列出所有已配置的项目及其区域

事件

工具	描述
`clevertap_upload_events`	为用户上传一个或多个事件
`clevertap_get_events`	使用过滤器查询事件数据
`clevertap_get_events_cursor`	通过游标获取下一页事件结果
`clevertap_get_event_count`	获取事件的总计数（支持异步轮询）

用户画像

工具	描述
`clevertap_upload_profiles`	创建或更新用户画像
`clevertap_get_profile`	通过身份、电子邮件或 objectId 查找单个用户
`clevertap_get_profiles_by_event`	获取执行过某事件的用户画像
`clevertap_get_profiles_cursor`	通过游标获取下一页画像结果
`clevertap_delete_profile`	删除用户画像
`clevertap_upload_device_token`	为用户注册推送令牌
`clevertap_get_profile_count`	计算匹配细分市场的画像数量
`clevertap_demerge_profiles`	拆分已合并的画像
`clevertap_subscribe`	订阅/取消订阅用户的渠道
`clevertap_disassociate_phone`	从画像中移除电话号码

营销活动

工具	描述
`clevertap_get_campaigns`	列出日期范围内的营销活动
`clevertap_get_campaign_report`	获取营销活动的投放和互动统计数据
`clevertap_stop_campaign`	停止正在运行的营销活动
`clevertap_create_campaign`	创建并启动营销活动

报告

工具	描述
`clevertap_get_message_report`	消息级投放报告
`clevertap_get_top_property_count`	事件的顶级属性值计数
`clevertap_get_event_trend`	事件的日/周/月趋势
`clevertap_get_dau`	日活跃用户趋势
`clevertap_get_uninstall_report`	卸载趋势报告
`clevertap_get_real_time_counts`	实时活跃用户计数

通用

工具	描述
`clevertap_request`	发起任何原始 REST API 请求
`clevertap_poll`	通过 `req_id` 轮询挂起的异步请求

Web / 浏览器

工具	描述
`clevertap_web_login`	打开 Chromium 窗口，并在手动登录后捕获仪表板会话 cookie + CSRF 令牌（支持 SSO 和 2FA）
`clevertap_web_session_status`	检查是否已为项目捕获 Web 会话，以及获取时间
`clevertap_web_request`	使用捕获的会话向任何 CleverTap 仪表板端点发起已认证的请求
`clevertap_get_campaigns_ui`	从仪表板 UI API 列出营销活动 — 比 REST API 提供更丰富的数据（状态、发送量、展示量、点击量、编辑 URL）
`clevertap_send_test_push`	向特定设备令牌发送测试推送通知。接受来自 `clevertap_get_profile` 的推送令牌 (`platformInfo[].push_token`)、目标平台 (`ios`/`android`)、推送渠道名称以及可选的深度链接 URL。

Web 工具前提条件： 在 npm install 后安装一次 Playwright Chromium 二进制文件：
npx playwright install chromium

安装

git clone https://github.com/your-org/clevertap-mcp.git
cd clevertap-mcp
npm install
npx playwright install chromium   # required for web/browser tools
npm run build

配置

服务器从 CLEVERTAP_PROJECTS 环境变量中读取项目凭据 — 这是一个项目对象的 JSON 数组：

[
  {
    "name": "My App - Production",
    "account_id": "XXX-XXX-XXXX",
    "passcode": "YYY-YYY-YYYY",
    "region": "us1"
  },
  {
    "name": "My App - Staging",
    "account_id": "AAA-AAA-AAAA",
    "passcode": "BBB-BBB-BBBB",
    "region": "us1"
  }
]

支持的区域： in1, us1, eu1, sg1, aps3, mec1

单项目回退

您也可以为单个项目使用单独的环境变量：

CLEVERTAP_ACCOUNT_ID=XXX-XXX-XXXX
CLEVERTAP_PASSCODE=YYY-YYY-YYYY
CLEVERTAP_REGION=us1

添加到 Claude Desktop

在您的 claude_desktop_config.json（或 ~/.claude.json）中：

{
  "mcpServers": {
    "clevertap": {
      "command": "node",
      "args": ["/absolute/path/to/clevertap-mcp/dist/index.js"],
      "env": {
        "CLEVERTAP_PROJECTS": "[{\"name\":\"My App\",\"account_id\":\"XXX-XXX-XXXX\",\"passcode\":\"YYY-YYY-YYYY\",\"region\":\"us1\"}]"
      }
    }
  }
}

重要： CLEVERTAP_PROJECTS 必须是 env 块内序列化的 JSON 字符串（而不是原生 JSON 对象）。

开发

npm run build      # compile TypeScript → dist/
npm run dev        # watch mode
npm start          # run compiled server

项目结构

src/
  index.ts          # MCP server entry point, project config, tool registration
  client.ts         # CleverTap REST API HTTP client
  tools/
    events.ts       # Event upload and query tools
    profiles.ts     # Profile management tools
    campaigns.ts    # Campaign tools
    reports.ts      # Analytics and report tools
    generic.ts      # Raw request / poll tools
    web.ts          # Browser session tools via Playwright (login, campaigns UI, test push)

许可证

MIT

clevertap-mcp

clevertap-mcp

功能特性

工具

元数据

事件

用户画像

营销活动

报告

通用

Web / 浏览器

安装

配置

单项目回退

添加到 Claude Desktop

开发

项目结构

许可证

Resources

Looking for Admin?

Tools

Latest Blog Posts

MCP directory API