youtube-analytics-mcp

MCP-сервер, который даёт ИИ-ассистенту всю поверхность API YouTube Analytics, Data v3 и Reporting для каналов, которыми вы владеете, — в том числе для нескольких каналов сразу.

Большинство MCP-серверов для YouTube жёстко зашивают несколько строк метрик, поэтому первый же вопрос вне их предустановленного списка остаётся без ответа, пока вы не сделаете форк. Этот построен наоборот: youtube_analytics_query принимает все параметры, которые принимает reports.query, а youtube_data_call / youtube_reporting_call делают то же самое для двух других API. Пресеты — это удобства поверх, а не единственный путь к результату.

Вы приносите собственный OAuth-клиент Google Cloud. В этот пакет ничего не встроено, никакие учётные данные не проходят через третьи стороны, и всё работает локально через stdio.

Инструменты

Каждый инструмент данных принимает необязательный параметр account, так что в одном разговоре можно сравнивать два канала.

Большие результаты сохраняются в файл, а не проходят через модель

youtube_analytics_query, youtube_data_call и youtube_reporting_call принимают outputPath (и необязательный format: csv или json, иначе он определяется по расширению). С ним полный результат записывается на диск, а возвращается только сводка — число строк, колонки, размер в байтах, первые три строки. Без него результаты более 100 строк обрезаются с указанием на эту опцию, потому что отчёт на тысячу строк, возвращённый инлайн, расходует окно контекста вызывающей стороны и становится нечитаемым.

Для действительно массовой работы — каждый день каждого видео, месяцами — используйте Reporting API через youtube_reporting_call: он создаёт загружаемые ежедневные CSV-отчёты с комбинациями измерений, которые reports.query не вернёт одним вызовом.

Related MCP server: YouTube MCP Server

Настройка

1. OAuth-клиент Google Cloud, один раз

• Создайте или выберите проект.

• APIs & Services → Library: включите YouTube Analytics API, YouTube Data API v3 и YouTube Reporting API.

• OAuth consent screen → Audience: установите тип пользователей External (Internal предлагается только тогда, когда подключена организация Workspace). На той же странице Audience, в разделе Test users, нажмите + Add users и добавьте аккаунт Google каждого владельца канала — включая ваш собственный.

  Пропустите это — и согласие завершится ошибкой «… has not completed the Google verification process. The app is currently being tested and can only be accessed by developer-approved testers.» То, что вы владелец проекта, не делает вас тестовым пользователем; вас нужно добавить явно.

• Установите статус публикации In production. Это важнее, чем кажется. Google:

  Проекту Google Cloud Platform с экраном согласия OAuth, настроенным для внешнего типа пользователей и статусом публикации "Testing", выдаётся refresh-токен со сроком действия 7 дней, если только единственные запрошенные области OAuth не являются подмножеством имени, адреса электронной почты и профиля пользователя.

  Все области YouTube чувствительны, поэтому приложение в статусе Testing заставляет вас повторно авторизоваться каждую неделю.

  Предупреждаем: публикация для этих областей — не просто переключатель. Консоль, скорее всего, потребует демонстрационное видео и отправит приложение на проверку YouTube API, прежде чем позволит выйти из статуса Testing. Для личного инструмента это настоящая работа, и еженедельное повторное согласие часто оказывается лучшим вариантом. Альтернативы см. в разделе Лимит гранта в 7 дней ниже.

• Credentials → Create credentials → OAuth client ID → Desktop app. Не Web application: этот сервер при каждом запуске слушает случайный свободный порт на loopback, а веб-клиент требует, чтобы каждый redirect URI, включая порт, был зарегистрирован заранее.

• Скачайте JSON.

2. Укажите серверу, где находится клиент

Поместите его в файл конфигурации (см. config.example.json):

// %APPDATA%\youtube-analytics-mcp\config.json          (Windows)
// ~/Library/Application Support/youtube-analytics-mcp/  (macOS)
// ~/.config/youtube-analytics-mcp/config.json           (Linux)
{
  "client": { "client_id": "...", "client_secret": "..." }
}

Выполните youtube-analytics-mcp --where, чтобы вывести этот каталог. Переменные окружения тоже работают и имеют приоритет — YTMCP_CLIENT_ID + YTMCP_CLIENT_SECRET или YTMCP_CLIENT_FILE, указывающий на файл, скачанный из Google, без изменений (обёртка {"installed": …} снимается за вас). YTMCP_CONFIG_DIR перемещает весь каталог.

3. Авторизуйте каждый канал

bun run auth                      # or: youtube-analytics-mcp --authorize
bun run auth -- --alias second    # name it yourself

Ваш браузер откроется на странице согласия автоматически; URL также выводится для случаев, когда открыть браузер нельзя (SSH, контейнеры, CI). Выберите аккаунт Google, которому принадлежит канал, и подтвердите. Повторите для каждого канала — каждый раз выбирайте в браузере другой аккаунт. Аккаунты называются по их @handle, если вы не передадите --alias.

Установите YTMCP_NO_BROWSER=1, чтобы браузер никогда не запускался, или передайте openBrowser: false инструменту youtube_authorize для одного вызова.

Refresh-токены записываются в accounts.json в том же каталоге, отдельно от config.json, который вы правите вручную, так что файл, который вы можете вставить в отчёт об ошибке, никогда не будет файлом с токенами. Оба файла записываются с правами 0600 там, где платформа это поддерживает.

Ваш ассистент тоже может этим управлять. youtube_authorize сразу возвращает URL согласия и продолжает слушать в фоне; youtube_authorize_status сообщает, чем всё закончилось. Он не блокируется, потому что согласие занимает столько времени, сколько нужно человеку, а MCP-клиенты отказываются от вызова инструмента задолго до этого. URL также записывается в pending-auth.txt в каталоге конфигурации, поскольку большинство клиентов отбрасывают stderr сервера, а URL, который никто не может прочитать, бесполезен.

4. Зарегистрируйте сервер в вашем MCP-клиенте

Claude Code:

claude mcp add youtube-analytics --scope user -- bunx youtube-analytics-mcp

Или вручную в карте mcpServers любого клиента:

{
  "mcpServers": {
    "youtube-analytics": { "command": "bunx", "args": ["youtube-analytics-mcp"] }
  }
}

По умолчанию только чтение

Обновление видео, публикация или модерация комментариев и загрузка миниатюр необратимы на живом канале, поэтому область на запись не запрашивается, а вызовы, отличные от GET, отклоняются. Чтобы включить их, установите YTMCP_ALLOW_WRITE=1 и повторно авторизуйтесь — сам по себе флаг ничего не делает, потому что сохранённый токен не содержит этой области.

Одновременные зрители и форма запроса, о которой никто не догадывается

averageConcurrentViewers и peakConcurrentViewers действительно работают для завершённых трансляций и точно совпадают с числами самого Studio. Широко распространено мнение, что их не существует, потому что API отвергает их во всех формах, кроме одной: фильтр должен закреплять одно видео и dimensions должен быть livestreamPosition.

Ни одна ошибка не называет недостающее измерение, а ошибка 500 в частности выглядит так, будто сломана метрика, а не запрос. youtube_concurrent_curve собирает этот запрос за вас и возвращает пик, среднее и всю поминутную кривую.

Чего оно действительно не может вам дать

youtube_capabilities возвращает актуальный список. Оба пункта проверены запросом метрики и получением Unknown identifier — так API отличает имя, о котором никогда не слышал, от того, которое знает, но не может обслужить здесь:

• Суммарное количество сообщений и реакций в чате трансляции. Только в Studio. liveChatMessages читает чат в реальном времени и не может восстановить завершившийся.

• Показы и рейтинг кликов по показам (CTR). Только в Studio, на вкладке Reach.

Два полезных факта

Окна «с момента публикации» не существует. Analytics API работает строго по диапазонам дат, поэтому окно, покрывающее день трансляции, по построению возвращает живую аудиторию этой трансляции. Окно Studio по умолчанию для каждого видео исключает весь период прямой трансляции — это лёгкая и дорогостоящая ловушка при анализе трансляций. Этот API в неё попасть не может.

Квота Analytics отдельная. API Analytics и Reporting тарифицируются независимо от суточного бюджета единиц Data API v3, поэтому запросы здесь не расходуют квоту, за которую конкурирует опрос чата трансляции. Сильный вывод из того, что это отдельные API со своими страницами квот в консоли, — не измерено.

Разработка

bun install
bun run dev          # start on stdio
bunx tsc --noEmit    # typecheck
bun run inspector    # MCP Inspector

MIT.

API отстаёт на несколько дней

Итоговые данные Analytics доступны не сразу. Измерено 2026-08-25: строки с измерением по дням доходили до 08-22 и обрывались — сессии за предыдущие три дня не возвращали вообще никаких строк, а не нулевые строки. Запрос по трансляции, завершившейся несколько часов назад, будет выглядеть как канал без трафика.

Веб-интерфейс Studio имеет путь в реальном времени, которого API не предоставляет, поэтому отчётность за текущий день по-прежнему должна браться из Studio. Используйте этот сервер для всего, что старше примерно трёх дней — здесь он гораздо лучше, чем просматривать Studio видео за видео.

Лимит гранта в 7 дней и почему никакой код не может его обойти

Пока статус публикации Cloud-проекта — Testing с типом пользователей External, Google отзывает refresh-токены через 7 дней, если только единственные запрошенные области — не имя, электронная почта и профиль. Все области YouTube чувствительны, поэтому это исключение здесь не применимо никогда.

Это нельзя автоматизировать. Семидневный срок относится к refresh-токену. Выпуск нового требует, чтобы человек одобрил экран согласия в браузере — именно это и означает согласие, а не пробел, который можно обойти инженерно. Более частое обновление access-токенов на это не влияет.

Что вместо этого делает этот сервер:

• youtube_accounts сообщает ageDays каждого гранта и предупреждает с 5-го дня.

• Истёкший грант завершается ошибкой с сообщением, называющим причину и решение, а не голым invalid_grant.

• youtube_refresh_tokens (или --refresh из CLI) проверяет каждый грант как проверку работоспособности. Это также страховка: не установлено, отсчитывается ли 7-дневный срок абсолютно с момента выдачи или сдвигается при использовании. Если он сдвигается, ежедневный запуск по расписанию поддерживает гранты живыми бесконечно; если нет, вызов почти ничего не стоит. В любом случае запускать стоит.

• Повторное согласие — это один вызов youtube_authorize, который сам открывает браузер, — около пятнадцати секунд.

Настоящие решения, в порядке возрастания затрат:

1. Статус публикации → В продакшене. Бесплатно, и срок действия разрешений перестаёт истекать. Для чувствительных областей YouTube Google может потребовать демо-видео и проверку перед публикацией, что является реальным объёмом работы для личного инструмента.

2. Внутренний тип пользователя. Нет ограничения в 7 дней и нет проверки, но эта опция доступна только когда проект принадлежит организации Google Workspace — платной подписке.

3. Live с еженедельным повторным согласием. Для инструмента одного пользователя это часто правильный ответ.