vturb-mcp

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

Built with the same pattern as hotmart-mcp: TypeScript + @modelcontextprotocol/sdk + zod.

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.nome-do-cliente

# Edit and paste your token
# .env.paula-ardanza
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.nome-do-cliente"
      }
    }
  }
}

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.paula-ardanza"
      }
    }
  }
}

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.outro-cliente"

Available Tools

Discovery & Monitoring

Session Analytics

Events

Engagement & Retention

Clicks

Conversions

Traffic Origin

Dashboard Summary

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