vturb-mcp

MCP server for the vTurb Analytics API — exposes 15 tools to query real-time and historical video analytics directly from Claude.

---

Features

• 15 analytics tools covering sessions, events, engagement, clicks, conversions, traffic origin and more
• Built-in rate limiter — token bucket enforcing the Pro tier limit of 120 req/min (no 429 errors)
• Smart player detection — find_active_players auto-discovers which video is live today
• Per-client .env files — clean credential management across multiple accounts

---

Requirements

• Node.js ≥ 18
• A vTurb account with Analytics API access
• Your API token from app.vturb.com/settings/analytics-api
• Claude Code (CLI or VSCode extension)

---

Installation

1. Clone the repository

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

2. Create your .env file for each client

The MCP uses a per-client .env file so you can manage multiple vTurb accounts cleanly. Name the file after the client:

# Copy the example
cp .env.example .env.customer-name

# Edit and paste your token
# .env.customer-name
VTURB_API_TOKEN=your_token_here

The file format is simple — one variable per line:

VTURB_API_TOKEN=eyJ...

Security: Never commit .env.* files. They are already in .gitignore.

3. Register the MCP server in Claude Code

Open ~/.claude/mcp.json (create it if it doesn't exist) and add:

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

Windows example:

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

4. Restart Claude Code

The MCP server starts automatically on the next session. You'll see it listed in your available tools.

---

Switching between clients

To switch accounts, just update VTURB_ENV_FILE in mcp.json to point to a different .env file and restart Claude:

"VTURB_ENV_FILE": "F:\\local-mcps\\vturb-mcp\\.env.other-customer"

---

Available Tools

Discovery & Monitoring

Tool	Description
list_players	Lists all players in the account with id, name, duration, and pitch_time. Supports optional filters by name and date range.
find_active_players	Smart tool. Lists all players, checks which ones have activity today, and returns only the active ones with their metadata. Use this first to discover the correct player_id.
get_quota_usage	Returns the current API quota status: queries used, remaining, and reset time. Use this to monitor consumption and avoid hitting the 120 req/min limit.
get_live_users	Returns the number of users currently watching, broken down by domain. Configurable time window (1–720 minutes).

Session Analytics

Tool	Description
get_session_stats	Main analytics dashboard for a player: total views, plays, unique sessions/devices, engagement rate, clicks, conversions, and revenue in BRL/USD/EUR.
get_session_stats_by_day	Same metrics as get_session_stats but broken down day by day. Ideal for historical trend analysis.

Events

Tool	Description
get_events_total	Returns totals for started, finished, and/or viewed events with unique session and device counts.
get_events_by_day	Same event totals broken down by day for trend analysis.

Engagement & Retention

Tool	Description
get_user_engagement	Returns the video retention curve: how many users are still watching at each second. Also returns average_watched_time and engagement_rate.
get_user_engagement_by_day	Returns the engagement rate per day over the selected period.

Clicks

Tool	Description
get_clicks_timed	Returns CTA click counts grouped by video second. Identifies the moment in the video that drives the most intent.
get_clicks_by_day	CTA click totals broken down by day.

Conversions

Tool	Description
get_conversions_by_day	Conversion totals grouped by day, with unique session and device counts.

Traffic Origin

Tool	Description
get_traffic_origin_stats	Breaks down session metrics by traffic source. Supports utm_source, utm_medium, utm_campaign, utm_content, utm_term, src, sck.

Dashboard Summary

Tool	Description
get_headlines_stats	Returns a pre-computed summary (views, plays, engagement rate, clicks, and conversion rate) — the same numbers shown in the vTurb dashboard header.

---

Typical Workflow

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

---

Rate Limiting

The client uses a token bucket algorithm configured for the Pro tier:

• Limit: 120 requests per minute
• Refill rate: 2 tokens per second
• Behavior: requests wait automatically if the bucket is empty — no errors thrown, no retries needed

Use get_quota_usage to check live consumption from vTurb's side.

---

Project Structure

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 Reference

• vTurb Analytics API Docs
• Base URL: https://analytics.vturb.net
• Auth headers: X-Api-Token + X-Api-Version: v1

---

License

MIT