Skip to main content
Glama
deenesjakoruzh
hiperbold

vturb-mcp

by hiperbold
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

vturb-mcp

vTurb Analytics API 用のMCPサーバー — Claudeから直接リアルタイムおよび過去の動画分析をクエリするための15個のツールを提供します。

hotmart-mcp と同じパターンで構築されています：TypeScript + @modelcontextprotocol/sdk + zod。

特徴

  • 15個の分析ツール：セッション、イベント、エンゲージメント、クリック、コンバージョン、トラフィック元などを網羅

  • レート制限機能内蔵 — トークンバケット方式により、Proティアの制限である120リクエスト/分を強制（429エラーは発生しません）

  • スマートプレイヤー検出 — find_active_players が今日アクティブな動画を自動的に発見

  • クライアントごとの .env ファイル — 複数のアカウント間でクリーンな認証情報管理が可能

Related MCP server: MCP YouTube Intelligence

要件

  • Node.js ≥ 18

  • Analytics APIアクセス権を持つvTurbアカウント

  • app.vturb.com/settings/analytics-api から取得したAPIトークン

  • Claude Code (CLIまたはVSCode拡張機能)

インストール

1. リポジトリのクローン

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

2. クライアントごとに .env ファイルを作成

このMCPはクライアントごとに .env ファイルを使用するため、複数のvTurbアカウントをクリーンに管理できます。ファイル名はクライアント名にしてください：

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

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

ファイル形式はシンプルで、1行に1つの変数を記述します：

VTURB_API_TOKEN=eyJ...

セキュリティ: .env.* ファイルをコミットしないでください。これらはすでに .gitignore に含まれています。

3. Claude CodeにMCPサーバーを登録

~/.claude/mcp.json を開き（存在しない場合は作成）、以下を追加します：

{
  "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の例:

{
  "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の再起動

MCPサーバーは次のセッションで自動的に起動します。利用可能なツールリストに表示されます。

クライアントの切り替え

アカウントを切り替えるには、mcp.json 内の VTURB_ENV_FILE を別の .env ファイルを指すように更新し、Claudeを再起動するだけです：

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

利用可能なツール

発見と監視

ツール

説明

list_players

アカウント内のすべてのプレイヤーを id、name、duration、pitch_time とともにリストアップします。名前や日付範囲によるオプションのフィルタリングをサポートしています。

find_active_players

スマートツール。 すべてのプレイヤーをリストアップし、今日アクティブなプレイヤーを確認して、メタデータとともにアクティブなプレイヤーのみを返します。正しい player_id を見つけるために最初にこれを使用してください。

get_quota_usage

現在のAPIクォータステータス（使用済みクエリ、残り、リセット時間）を返します。消費量を監視し、120リクエスト/分の制限に達しないようにするために使用します。

get_live_users

現在視聴中のユーザー数をドメイン別に分類して返します。時間枠（1〜720分）を設定可能です。

セッション分析

ツール

説明

get_session_stats

プレイヤーの主要な分析ダッシュボード：総ビュー数、再生数、ユニークセッション/デバイス数、エンゲージメント率、クリック数、コンバージョン数、およびBRL/USD/EURでの収益。

get_session_stats_by_day

get_session_stats と同じ指標ですが、日別に分類されます。過去の傾向分析に最適です。

イベント

ツール

説明

get_events_total

started、finished、および/または viewed イベントの合計を、ユニークセッション数およびデバイス数とともに返します。

get_events_by_day

傾向分析のために日別に分類された同じイベント合計。

エンゲージメントとリテンション

ツール

説明

get_user_engagement

動画のリテンション曲線（各秒で何人のユーザーが視聴し続けているか）を返します。また、average_watched_time（平均視聴時間）と engagement_rate（エンゲージメント率）も返します。

get_user_engagement_by_day

選択した期間の日ごとのエンゲージメント率を返します。

クリック

ツール

説明

get_clicks_timed

動画の秒数ごとにグループ化されたCTAクリック数を返します。最も意図を喚起する動画内の瞬間を特定します。

get_clicks_by_day

日別に分類されたCTAクリック合計。

コンバージョン

ツール

説明

get_conversions_by_day

ユニークセッション数およびデバイス数とともに、日別にグループ化されたコンバージョン合計。

トラフィック元

ツール

説明

get_traffic_origin_stats

トラフィックソース別にセッション指標を分類します。utm_source、utm_medium、utm_campaign、utm_content、utm_term、src、sck をサポートしています。

ダッシュボードの概要

ツール

説明

get_headlines_stats

事前に計算された概要（ビュー数、再生数、エンゲージメント率、クリック数、コンバージョン率）を返します。vTurbダッシュボードのヘッダーに表示される数値と同じです。

一般的なワークフロー

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

レート制限

クライアントはProティア用に構成された トークンバケット アルゴリズムを使用します：

  • 制限: 1分あたり120リクエスト

  • 補充レート: 1秒あたり2トークン

  • 動作: バケットが空の場合、リクエストは自動的に待機します — エラーはスローされず、再試行も不要です

vTurb側からのライブ消費量を確認するには get_quota_usage を使用してください。

プロジェクト構造

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リファレンス

ライセンス

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