clevertap-mcp

CleverTap REST API를 위한 Model Context Protocol (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`	일간 활성 사용자(DAU) 추세
`clevertap_get_uninstall_report`	앱 삭제 추세 보고서
`clevertap_get_real_time_counts`	실시간 활성 사용자 수

일반

도구	설명
`clevertap_request`	원시 REST API 요청 수행
`clevertap_poll`	`req_id`를 사용하여 보류 중인 비동기 요청 폴링

웹 / 브라우저

도구	설명
`clevertap_web_login`	Chromium 창을 열고 수동 로그인 후 대시보드 세션 쿠키 및 CSRF 토큰 캡처(SSO 및 2FA 지원)
`clevertap_web_session_status`	프로젝트에 대해 웹 세션이 캡처되었는지, 언제 획득되었는지 확인
`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을 허용합니다.

웹 도구 필수 조건: 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

주요 기능

도구

메타

이벤트

프로필

캠페인

보고서

일반

웹 / 브라우저

설치

구성

단일 프로젝트 대체

Claude Desktop에 추가

개발

프로젝트 구조

라이선스

Resources

Looking for Admin?

Tools

Latest Blog Posts

MCP directory API