How do I use vturb-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@vturb-mcp find active players for today" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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

vturb-mcp

vturb-mcp

Features

Requirements

Installation

1. Clone the repository

2. Create your `.env` file for each client

3. Register the MCP server in Claude Code

4. Restart Claude Code

Switching between clients

Available Tools

Discovery & Monitoring

Session Analytics

Events

Engagement & Retention

Clicks

Conversions

Traffic Origin

Dashboard Summary

Typical Workflow

Rate Limiting

Project Structure

API Reference

License

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API

vturb-mcp

Features

Requirements

Installation

1. Clone the repository

2. Create your .env file for each client

3. Register the MCP server in Claude Code

4. Restart Claude Code

Switching between clients

Available Tools

Discovery & Monitoring

Session Analytics

Events

Engagement & Retention

Clicks

Conversions

Traffic Origin

Dashboard Summary

Typical Workflow

Rate Limiting

Project Structure

API Reference

License

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API

2. Create your `.env` file for each client