Skip to main content
Glama
deenesjakoruzh
hiperbold

vturb-mcp

by hiperbold
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

vturb-mcp

MCP-Server für die vTurb Analytics API — stellt 15 Tools bereit, um Echtzeit- und historische Videoanalysen direkt aus Claude abzufragen.

Entwickelt nach dem gleichen Muster wie hotmart-mcp: TypeScript + @modelcontextprotocol/sdk + zod.

Funktionen

  • 15 Analyse-Tools für Sitzungen, Ereignisse, Engagement, Klicks, Conversions, Traffic-Herkunft und mehr

  • Integriertes Rate-Limiting — Token-Bucket-Algorithmus zur Einhaltung des Pro-Tier-Limits von 120 Anfragen/Min (keine 429-Fehler)

  • Intelligente Player-Erkennung — find_active_players erkennt automatisch, welches Video heute live ist

  • Client-spezifische .env-Dateien — saubere Verwaltung von Anmeldedaten für mehrere Konten

Related MCP server: MCP YouTube Intelligence

Anforderungen

Installation

1. Repository klonen

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

2. .env-Datei für jeden Client erstellen

Das MCP verwendet eine .env-Datei pro Client, damit Sie mehrere vTurb-Konten sauber verwalten können. Benennen Sie die Datei nach dem 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

Das Dateiformat ist einfach — eine Variable pro Zeile:

VTURB_API_TOKEN=eyJ...

Sicherheit: Committen Sie niemals .env.*-Dateien. Sie sind bereits in der .gitignore enthalten.

3. MCP-Server in Claude Code registrieren

Öffnen Sie ~/.claude/mcp.json (erstellen Sie die Datei, falls sie nicht existiert) und fügen Sie Folgendes hinzu:

{
  "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-Beispiel:

{
  "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. Claude Code neu starten

Der MCP-Server startet automatisch bei der nächsten Sitzung. Sie sehen ihn in Ihren verfügbaren Tools aufgelistet.

Wechseln zwischen Clients

Um das Konto zu wechseln, aktualisieren Sie einfach VTURB_ENV_FILE in der mcp.json, um auf eine andere .env-Datei zu verweisen, und starten Sie Claude neu:

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

Verfügbare Tools

Erkennung & Überwachung

Tool

Beschreibung

list_players

Listet alle Player im Konto mit id, name, duration und pitch_time auf. Unterstützt optionale Filter nach Name und Datumsbereich.

find_active_players

Intelligentes Tool. Listet alle Player auf, prüft, welche heute aktiv sind, und gibt nur die aktiven Player mit ihren Metadaten zurück. Verwenden Sie dies zuerst, um die korrekte player_id zu finden.

get_quota_usage

Gibt den aktuellen API-Kontingentstatus zurück: verbrauchte Abfragen, verbleibende Abfragen und Rücksetzzeit. Verwenden Sie dies, um den Verbrauch zu überwachen und das Limit von 120 Anfragen/Min nicht zu überschreiten.

get_live_users

Gibt die Anzahl der aktuell zuschauenden Benutzer zurück, aufgeschlüsselt nach Domain. Konfigurierbares Zeitfenster (1–720 Minuten).

Sitzungsanalysen

Tool

Beschreibung

get_session_stats

Haupt-Dashboard für einen Player: Gesamtansichten, Wiedergaben, eindeutige Sitzungen/Geräte, Engagement-Rate, Klicks, Conversions und Umsatz in BRL/USD/EUR.

get_session_stats_by_day

Gleiche Metriken wie get_session_stats, aber tageweise aufgeschlüsselt. Ideal für historische Trendanalysen.

Ereignisse

Tool

Beschreibung

get_events_total

Gibt Summen für started-, finished- und/oder viewed-Ereignisse mit eindeutigen Sitzungs- und Gerätezahlen zurück.

get_events_by_day

Gleiche Ereignissummen tageweise aufgeschlüsselt für Trendanalysen.

Engagement & Bindung

Tool

Beschreibung

get_user_engagement

Gibt die Video-Retentionskurve zurück: wie viele Benutzer pro Sekunde noch zuschauen. Gibt auch average_watched_time und engagement_rate zurück.

get_user_engagement_by_day

Gibt die Engagement-Rate pro Tag über den ausgewählten Zeitraum zurück.

Klicks

Tool

Beschreibung

get_clicks_timed

Gibt die Anzahl der CTA-Klicks gruppiert nach Videosekunde zurück. Identifiziert den Moment im Video, der die meiste Interaktion erzeugt.

get_clicks_by_day

CTA-Klicksummen tageweise aufgeschlüsselt.

Conversions

Tool

Beschreibung

get_conversions_by_day

Conversion-Summen gruppiert nach Tag, mit eindeutigen Sitzungs- und Gerätezahlen.

Traffic-Herkunft

Tool

Beschreibung

get_traffic_origin_stats

Schlüsselt Sitzungsmetriken nach Traffic-Quelle auf. Unterstützt utm_source, utm_medium, utm_campaign, utm_content, utm_term, src, sck.

Dashboard-Zusammenfassung

Tool

Beschreibung

get_headlines_stats

Gibt eine vorausberechnete Zusammenfassung zurück (Ansichten, Wiedergaben, Engagement-Rate, Klicks und Conversion-Rate) — dieselben Zahlen, die im vTurb-Dashboard-Header angezeigt werden.

Typischer Arbeitsablauf

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

Der Client verwendet einen Token-Bucket-Algorithmus, der für das Pro-Tier konfiguriert ist:

  • Limit: 120 Anfragen pro Minute

  • Auffüllrate: 2 Token pro Sekunde

  • Verhalten: Anfragen warten automatisch, wenn der Bucket leer ist — keine Fehler, keine Wiederholungsversuche erforderlich

Verwenden Sie get_quota_usage, um den Live-Verbrauch von der vTurb-Seite aus zu überprüfen.

Projektstruktur

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-Referenz

Lizenz

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