Skip to main content
Glama
deenesjakoruzh
hiperbold

vturb-mcp

by hiperbold
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

vturb-mcp

Servidor MCP para la API de Analytics de vTurb — expone 15 herramientas para consultar analíticas de video en tiempo real e históricas directamente desde Claude.

Construido con el mismo patrón que hotmart-mcp: TypeScript + @modelcontextprotocol/sdk + zod.

Características

  • 15 herramientas de analítica que cubren sesiones, eventos, interacción, clics, conversiones, origen del tráfico y más.

  • Limitador de tasa integrado — token bucket que aplica el límite del plan Pro de 120 peticiones/min (sin errores 429).

  • Detección inteligente de reproductores — find_active_players descubre automáticamente qué video está activo hoy.

  • Archivos .env por cliente — gestión limpia de credenciales entre múltiples cuentas.

Related MCP server: MCP YouTube Intelligence

Requisitos

Instalación

1. Clonar el repositorio

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

2. Crear tu archivo .env para cada cliente

El MCP utiliza un archivo .env por cliente para que puedas gestionar múltiples cuentas de vTurb de forma limpia. Nombra el archivo según el cliente:

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

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

El formato del archivo es sencillo — una variable por línea:

VTURB_API_TOKEN=eyJ...

Seguridad: Nunca subas archivos .env.* al repositorio. Ya están incluidos en .gitignore.

3. Registrar el servidor MCP en Claude Code

Abre ~/.claude/mcp.json (créalo si no existe) y añade:

{
  "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"
      }
    }
  }
}

Ejemplo en 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. Reiniciar Claude Code

El servidor MCP se inicia automáticamente en la siguiente sesión. Lo verás listado en tus herramientas disponibles.

Cambiar entre clientes

Para cambiar de cuenta, simplemente actualiza VTURB_ENV_FILE en mcp.json para apuntar a un archivo .env diferente y reinicia Claude:

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

Herramientas disponibles

Descubrimiento y monitoreo

Herramienta

Descripción

list_players

Lista todos los reproductores de la cuenta con id, name, duration y pitch_time. Soporta filtros opcionales por nombre y rango de fechas.

find_active_players

Herramienta inteligente. Lista todos los reproductores, comprueba cuáles tienen actividad hoy y devuelve solo los activos con sus metadatos. Úsala primero para descubrir el player_id correcto.

get_quota_usage

Devuelve el estado actual de la cuota de la API: consultas utilizadas, restantes y tiempo de reinicio. Úsala para monitorear el consumo y evitar alcanzar el límite de 120 peticiones/min.

get_live_users

Devuelve el número de usuarios viendo actualmente, desglosado por dominio. Ventana de tiempo configurable (1–720 minutos).

Analíticas de sesión

Herramienta

Descripción

get_session_stats

Panel principal de analíticas para un reproductor: total de vistas, reproducciones, sesiones/dispositivos únicos, tasa de interacción, clics, conversiones e ingresos en BRL/USD/EUR.

get_session_stats_by_day

Las mismas métricas que get_session_stats pero desglosadas día a día. Ideal para análisis de tendencias históricas.

Eventos

Herramienta

Descripción

get_events_total

Devuelve totales para eventos started, finished y/o viewed con conteos únicos de sesión y dispositivo.

get_events_by_day

Los mismos totales de eventos desglosados por día para análisis de tendencias.

Interacción y retención

Herramienta

Descripción

get_user_engagement

Devuelve la curva de retención del video: cuántos usuarios siguen viendo en cada segundo. También devuelve average_watched_time y engagement_rate.

get_user_engagement_by_day

Devuelve la tasa de interacción por día durante el periodo seleccionado.

Clics

Herramienta

Descripción

get_clicks_timed

Devuelve conteos de clics en CTA agrupados por segundo de video. Identifica el momento en el video que genera más intención.

get_clicks_by_day

Totales de clics en CTA desglosados por día.

Conversiones

Herramienta

Descripción

get_conversions_by_day

Totales de conversión agrupados por día, con conteos únicos de sesión y dispositivo.

Origen del tráfico

Herramienta

Descripción

get_traffic_origin_stats

Desglosa las métricas de sesión por fuente de tráfico. Soporta utm_source, utm_medium, utm_campaign, utm_content, utm_term, src, sck.

Resumen del panel

Herramienta

Descripción

get_headlines_stats

Devuelve un resumen precalculado (vistas, reproducciones, tasa de interacción, clics y tasa de conversión) — los mismos números que se muestran en el encabezado del panel de vTurb.

Flujo de trabajo típico

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

Limitación de tasa

El cliente utiliza un algoritmo de token bucket configurado para el nivel Pro:

  • Límite: 120 peticiones por minuto

  • Tasa de recarga: 2 tokens por segundo

  • Comportamiento: las peticiones esperan automáticamente si el bucket está vacío — no se lanzan errores, no se necesitan reintentos

Usa get_quota_usage para comprobar el consumo en tiempo real desde el lado de vTurb.

Estructura del proyecto

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

Referencia de la API

Licencia

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