How do I use vturb-mcp?

1. Click on "Deploy 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.

de en es ja ko ru zh

vturb-mcp

by hiperbold

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

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

Related MCP server: MCP YouTube Intelligence

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

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

ActivityInactive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

mcpulse AOAuth
com.getmcpulse
Analytics for MCP servers. Query your tool calls, first-call success, retries and schema cost.
Data Visualization Monitoring Observability
331
MCPulse AOAuth
com.getmcpulse.api
Analytics for MCP servers. Find out which of your tools agents get wrong. MCPulse shows you which tools AI agents retry, which come back empty, and which they never call at all. Two lines inside your own server. It never sees your arguments or your results. getmcpulse.com
Data Visualization Monitoring Observability
331
Clamp AnalyticsOAuth
sh.clamp
Clamp Analytics MCP server: traffic, revenue, funnels, cohorts, errors, and search, for AI agents.
Monitoring Search
2
clipkit A
dev.clipkit
MCP server for Clipkit — gives AI agents a video toolbox via the Clipkit schema.
Multimedia Processing Image & Video Processing
15217

Related MCP Servers

YouTube Analytics MCP Serverofficial
Databases RAG Systems
CDataSoftware
A
license
Not graded
quality
D
maintenance
This read-only MCP Server allows you to connect to YouTube Analytics data from Claude Desktop through CData JDBC Drivers. Free (beta) read/write servers available at https://www.cdata.com/solutions/mcp
Updated a year ago (2025-10-18 19:19 UTC)
1
MIT
MCP YouTube Intelligence
Multimedia Processing Text Summarization Search
JangHyuckYun
A
license
A
quality
B
maintenance
An MCP server for intelligent YouTube video analysis that provides token-optimized summaries, sentiment analysis, and entity extraction from transcripts. It enables AI assistants to perform video reporting, channel monitoring, and comprehensive YouTube searches through structured data tools.
Updated 13 days ago (2026-09-08 12:45 UTC)
10
52
Apache 2.0
mcp-video-vision
Image & Video Processing Multimedia Processing
danusiojr
F
license
B
quality
D
maintenance
MCP server that enables video analysis capabilities to Claude, including frame extraction, scene detection, and video metadata retrieval.
Updated 3 months ago (2026-06-22 22:25 UTC)
8
-
@vivideo/mcp
Image & Video Processing Multimedia Processing
egocen-vivideo
A
license
Not graded
quality
C
maintenance
MCP server providing 13 agent-friendly tools for video creation and management via the Vivideo API, with built-in rate limiting, retries, and secret redaction.
Updated 2 months ago (2026-07-28 13:42 UTC)
MIT

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

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

YouTube Analytics MCP Serverofficial

MCP YouTube Intelligence

mcp-video-vision

@vivideo/mcp

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