Skip to main content
Glama
deenesjakoruzh
hiperbold

vturb-mcp

by hiperbold
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

vturb-mcp

vTurb Analytics API용 MCP 서버 — Claude에서 실시간 및 과거 비디오 분석을 직접 쿼리할 수 있는 15개의 도구를 제공합니다.

hotmart-mcp와 동일한 패턴으로 구축되었습니다: TypeScript + @modelcontextprotocol/sdk + zod.

기능

  • 15개의 분석 도구: 세션, 이벤트, 참여도, 클릭, 전환, 트래픽 출처 등을 포함

  • 내장 속도 제한기: Pro 티어 제한인 분당 120회 요청을 준수하는 토큰 버킷 (429 오류 없음)

  • 스마트 플레이어 감지: find_active_players가 오늘 활성화된 비디오를 자동으로 검색

  • 클라이언트별 .env 파일: 여러 계정 간의 깔끔한 자격 증명 관리

Related MCP server: MCP YouTube Intelligence

요구 사항

  • Node.js ≥ 18

  • Analytics API 액세스 권한이 있는 vTurb 계정

  • app.vturb.com/settings/analytics-api에서 발급받은 API 토큰

  • Claude Code (CLI 또는 VSCode 확장 프로그램)

설치

1. 저장소 복제

git clone https://github.com/hiperbold/vturb-mcp.git
cd vturb-mcp
npm install
npm run build

2. 각 클라이언트용 .env 파일 생성

MCP는 클라이언트별 .env 파일을 사용하여 여러 vTurb 계정을 깔끔하게 관리할 수 있습니다. 클라이언트 이름을 따서 파일 이름을 지정하세요:

# Copy the example
cp .env.example .env.nome-do-cliente

# Edit and paste your token
# .env.paula-ardanza
VTURB_API_TOKEN=your_token_here

파일 형식은 간단합니다. 한 줄에 하나의 변수를 입력하세요:

VTURB_API_TOKEN=eyJ...

보안: .env.* 파일을 커밋하지 마세요. 이미 .gitignore에 포함되어 있습니다.

3. Claude Code에 MCP 서버 등록

~/.claude/mcp.json을 열고(없으면 생성) 다음을 추가하세요:

{
  "mcpServers": {
    "vturb-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/vturb-mcp/dist/index.js"],
      "env": {
        "VTURB_ENV_FILE": "/absolute/path/to/vturb-mcp/.env.nome-do-cliente"
      }
    }
  }
}

Windows 예시:

{
  "mcpServers": {
    "vturb-mcp": {
      "command": "node",
      "args": ["F:\\local-mcps\\vturb-mcp\\dist\\index.js"],
      "env": {
        "VTURB_ENV_FILE": "F:\\local-mcps\\vturb-mcp\\.env.paula-ardanza"
      }
    }
  }
}

4. Claude Code 재시작

MCP 서버는 다음 세션에서 자동으로 시작됩니다. 사용 가능한 도구 목록에서 확인할 수 있습니다.

클라이언트 간 전환

계정을 전환하려면 mcp.json에서 VTURB_ENV_FILE을 다른 .env 파일을 가리키도록 업데이트하고 Claude를 재시작하세요:

"VTURB_ENV_FILE": "F:\\local-mcps\\vturb-mcp\\.env.outro-cliente"

사용 가능한 도구

검색 및 모니터링

도구

설명

list_players

계정의 모든 플레이어를 id, name, duration, pitch_time과 함께 나열합니다. 이름 및 날짜 범위별 필터를 지원합니다.

find_active_players

스마트 도구. 모든 플레이어를 나열하고 오늘 활동이 있는 플레이어를 확인하여 메타데이터와 함께 활성 플레이어만 반환합니다. 올바른 player_id를 찾으려면 이 도구를 먼저 사용하세요.

get_quota_usage

현재 API 할당량 상태(사용된 쿼리, 남은 쿼리, 재설정 시간)를 반환합니다. 소비량을 모니터링하고 분당 120회 요청 제한을 초과하지 않도록 하세요.

get_live_users

현재 시청 중인 사용자 수를 도메인별로 분류하여 반환합니다. 구성 가능한 시간 범위(1~720분)를 지원합니다.

세션 분석

도구

설명

get_session_stats

플레이어에 대한 주요 분석 대시보드: 총 조회수, 재생 수, 고유 세션/기기, 참여율, 클릭, 전환 및 BRL/USD/EUR 수익.

get_session_stats_by_day

get_session_stats와 동일한 지표를 일별로 분류합니다. 과거 추세 분석에 이상적입니다.

이벤트

도구

설명

get_events_total

started, finished 및/또는 viewed 이벤트의 총계를 고유 세션 및 기기 수와 함께 반환합니다.

get_events_by_day

추세 분석을 위해 일별로 분류된 동일한 이벤트 총계를 반환합니다.

참여 및 유지율

도구

설명

get_user_engagement

비디오 유지 곡선을 반환합니다: 각 초마다 시청 중인 사용자 수. 또한 average_watched_time 및 engagement_rate를 반환합니다.

get_user_engagement_by_day

선택한 기간 동안의 일일 참여율을 반환합니다.

클릭

도구

설명

get_clicks_timed

비디오 초 단위로 그룹화된 CTA 클릭 수를 반환합니다. 가장 많은 의도를 유도하는 비디오의 순간을 식별합니다.

get_clicks_by_day

일별로 분류된 CTA 클릭 총계입니다.

전환

도구

설명

get_conversions_by_day

고유 세션 및 기기 수와 함께 일별로 그룹화된 전환 총계입니다.

트래픽 출처

도구

설명

get_traffic_origin_stats

트래픽 소스별로 세션 지표를 분류합니다. utm_source, utm_medium, utm_campaign, utm_content, utm_term, src, sck를 지원합니다.

대시보드 요약

도구

설명

get_headlines_stats

vTurb 대시보드 헤더에 표시되는 것과 동일한 사전 계산된 요약(조회수, 재생 수, 참여율, 클릭 및 전환율)을 반환합니다.

일반적인 워크플로우

1. find_active_players          → discover which player_id is in use today
2. get_session_stats            → get the main KPIs for a date range
3. get_user_engagement          → inspect the retention curve
4. get_clicks_timed             → find when viewers click the CTA
5. get_conversions_by_day       → track conversion trends
6. get_traffic_origin_stats     → compare traffic sources

속도 제한

클라이언트는 Pro 티어에 맞게 구성된 토큰 버킷 알고리즘을 사용합니다:

  • 제한: 분당 120회 요청

  • 충전 속도: 초당 2토큰

  • 동작: 버킷이 비어 있으면 요청이 자동으로 대기합니다. 오류가 발생하지 않으며 재시도할 필요가 없습니다.

vTurb 측의 실시간 소비량을 확인하려면 get_quota_usage를 사용하세요.

프로젝트 구조

vturb-mcp/
  src/
    env.ts          — loads .env.* file at startup (via VTURB_ENV_FILE)
    client.ts       — rate-limited HTTP client (token bucket, 120 req/min)
    index.ts        — MCP server, registers all 15 tools
    tools/          — one file per tool
      list-players.ts
      find-active-players.ts
      get-quota-usage.ts
      get-session-stats.ts
      get-session-stats-by-day.ts
      get-events-total.ts
      get-events-by-day.ts
      get-user-engagement.ts
      get-user-engagement-by-day.ts
      get-clicks-timed.ts
      get-clicks-by-day.ts
      get-conversions-by-day.ts
      get-live-users.ts
      get-headlines-stats.ts
      get-traffic-origin-stats.ts
  dist/             — compiled output (run npm run build)
  .env.example      — template for creating client-specific env files

API 참조

라이선스

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers