vturb-mcp

MCP-сервер для API аналитики vTurb — предоставляет 15 инструментов для запроса видеоаналитики в реальном времени и исторических данных напрямую из Claude.

Создан по тому же принципу, что и hotmart-mcp: TypeScript + @modelcontextprotocol/sdk + zod.

Возможности

• 15 инструментов аналитики, охватывающих сессии, события, вовлеченность, клики, конверсии, источники трафика и многое другое

• Встроенный ограничитель частоты запросов (rate limiter) — алгоритм «маркерной корзины» (token bucket), обеспечивающий соблюдение лимита тарифа Pro в 120 запросов в минуту (без ошибок 429)

• Интеллектуальное обнаружение плееров — find_active_players автоматически находит видео, активные сегодня

• .env файлы для каждого клиента — удобное управление учетными данными для нескольких аккаунтов

Related MCP server: MCP YouTube Intelligence

Требования

• Node.js ≥ 18

• Аккаунт vTurb с доступом к API аналитики

• Ваш API-токен с app.vturb.com/settings/analytics-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

Формат файла прост — одна переменная на строку:

VTURB_API_TOKEN=eyJ...

Безопасность: Никогда не добавляйте файлы .env.* в систему контроля версий. Они уже добавлены в .gitignore.

3. Зарегистрируйте MCP-сервер в Claude Code

Откройте ~/.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-сервер запустится автоматически при следующей сессии. Вы увидите его в списке доступных инструментов.

Переключение между клиентами

Чтобы переключить аккаунты, просто обновите VTURB_ENV_FILE в mcp.json, указав путь к другому файлу .env, и перезапустите Claude:

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

Доступные инструменты

Обнаружение и мониторинг

Аналитика сессий

События

Вовлеченность и удержание

Клики

Конверсии

Источники трафика

Сводная панель

Типовой рабочий процесс

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)

Клиент использует алгоритм маркерной корзины (token bucket), настроенный для тарифа Pro:

• Лимит: 120 запросов в минуту

• Скорость пополнения: 2 токена в секунду

• Поведение: запросы автоматически ожидают, если корзина пуста — ошибки не возникают, повторные попытки не требуются

Используйте get_quota_usage для проверки текущего потребления со стороны vTurb.

Структура проекта

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

• Документация API аналитики vTurb

• Базовый URL: https://analytics.vturb.net

• Заголовки авторизации: X-Api-Token + X-Api-Version: v1

Лицензия

MIT