YouTube через API и MCP: 72 действия, три Google-скоупа и ловушка с загрузкой видео

Обзор

YouTube — не один API, а три под общим брендом: Data API v3 отвечает за канал, видео, плейлисты, комментарии и трансляции; Analytics API считает просмотры, удержание и деньги; Reporting API формирует массовые CSV-отчёты по расписанию. У всех трёх — общая авторизация через Google OAuth, но, как выяснилось при подключении, не общие права доступа.

Mira разбирает эту связку целиком — 72 действия — и отдаёт их в Claude через MCP. Ниже — что доступно на практике, где авторизация Google устроена не так, как ожидаешь, и почему часть привычных действий («загрузить видео») в этот список не попала осознанно, а не по недосмотру.

Что доступно владельцу канала

Итого 72 из них 41 меняет данные — деньги YouTube не берёт напрямую (квота API не тратит рубли), но изменение, удаление и публикация видны снаружи или необратимы, и барьер записи одинаков что для платного, что для «просто заметного».

Ловушки, которые стоит знать заранее

Аналитика недоступна на обычном чтении — и это не баг

Казалось бы естественным: подключил канал на чтение — получил и видео, и статистику. У YouTube не так. Скоупы yt-analytics.readonly и yt-analytics-monetary.readonly — своё, отдельное пространство доступа, не входящее ни в youtube.readonly, ни даже в полный youtube. Источник, подключённый в режиме «только чтение», физически не сможет вызвать ни один метод Analytics или Reporting API — не потому что мы это запретили, а потому что в его токене нет нужного скоупа вовсе.

Единственный способ получить отчётность — подключить источник с правом записи, даже если писать вы ничего не планируете. Мы прямо называем это в подсказке при подключении: без этого человек десять минут перечитывает сообщение об ошибке 403, пытаясь понять, какое право на запись ему не хватает, хотя вопрос вообще не про запись.

Загрузить видео через это подключение нельзя — и другие четыре действия тоже

videos.insert, captions.insert, thumbnails.set, watermarks.set, channelBanners.insert — все пять требуют multipart-загрузку файла: собственно видео, файл субтитров, картинку обложки или водяного знака. Это не JSON-запрос с полями, а поток байтов с другим протоколом целиком.

Решение — назвать это явно, а не сделать вид, что действия не существует. Пять действий отсутствуют в списке, и причина написана рядом: она такая же, как у похожей истории с публикацией объявлений на Авито — там тоже нет «обычного» способа создать объявление через API, только загрузка фида.

part — обязательный параметр почти везде, и про него легко забыть

Возврат данных в Data API устроен не как «отдай мне видео», а как «отдай мне ЧАСТИ видео» — snippet, status, contentDetails, statistics запрашиваются отдельно, и не названная часть просто не появится в ответе, без предупреждения. То же самое при изменении: обновить видео без part=snippet в запросе — значит не тронуть заголовок, даже если он передан в теле.

Разумное умолчание подставляется само: для списка видео это snippet,contentDetails,statistics, для канала — snippet,contentDetails,statistics. Не пришлось бы объяснять модели устройство параметра part, чтобы получить простой список видео.

Идентификатор ресурса — почти всегда параметр запроса, а не часть адреса

В отличие от многих REST API, DELETE /videos/{id} у YouTube не существует. Удаление видео — это DELETE /videos?id=VIDEO_ID, то есть идентификатор в query-строке, а не в пути. Из 72 действий путь как часть адреса использует лишь шестёрка: скачивание файла субтитров и вся работа с задачами массовой отчётности (Reporting API нумерует задачи и отчёты как вложенные ресурсы — /jobs/{id}/reports/{id}).

У одного из двух путевых параметров — буквальные слэши внутри значения

Скачивание готового отчёта (media.download) адресуется строкой вида jobs/<id>/reports/<id> — и Google прямо просит не кодировать в ней «/»: они не разделяют разные параметры, они часть ОДНОГО идентификатора ресурса. Обычная защита от обхода адреса (кодировать каждый спецсимвол) здесь ломает сам запрос — закодированный %2F адресует несуществующий ресурс. Это ровно тот редкий случай, ради которого в общем помощнике Mira для сборки адресов есть настройка «этому полю разрешено содержать буквальный слэш» — как у номера счёта в API Точка Банка.

Квота считается не запросами, а «единицами», и стоимость разная

10 000 единиц в день на проект в Google Cloud — это не 10 000 вызовов. Простое чтение стоит 1 единицу, search.list — 100, а любая запись — от 50. Опрос ленты поиска в цикле «на всякий случай» способен исчерпать дневную квоту меньше чем за сотню вызовов, и Google ответит на это своим отказом 403, не нашим.

Как это выглядит через MCP

MCP — открытый протокол, по которому Claude подключается к внешним данным и действиям. Вместо написания клиента для трёх разных Google API вы подключаете YouTube в кабинете Mira одной авторизацией и спрашиваете обычными словами.

Какие видео у меня получили больше всего просмотров за последний месяц?

Claude вызывает отчёт YouTube Analytics с нужными метриками и диапазоном дат — при условии, что канал подключён с правом записи: без него, как описано выше, у токена нет скоупа аналитики.

Есть новые комментарии, требующие модерации?

Список цепочек комментариев приходит с состоянием модерации по каждой, а не общим счётчиком.

Ответь на этот комментарий от имени канала: "..."

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

Что защищено от случайного действия

Барьер записи выведен из той же таблицы, что описывает адреса и параметры — разойтись им негде: разрешение на запись хранится в том же месте, что метод и путь, а не отдельным списком, который можно забыть обновить. Источник без права записи физически не отправит POST, PUT или DELETE — запрос обрывается раньше похода к Google.

Что это даёт на практике

Автору канала. Не нужно открывать YouTube Studio, чтобы узнать, какие видео растут, а какие комментарии ждут ответа, — можно спросить прямо в чате.

Медиа-команде. Планирование трансляций, модерация комментариев и обновление плейлистов — одним доступом, без переключения между вкладками Studio.

Разработчику. Готовый клиент вместо разбора трёх разных Discovery-документов Google: приведённые ошибки, известные пределы квоты, разведённые уровни доступа между чтением и аналитикой.

Как подключить

1. В Mira: проект → источники → YouTube → «Подключить».
2. Авторизоваться через Google и выбрать канал.
3. Если нужна аналитика и отчётность — отметить «Разрешить запись» уже на этом шаге: добавить её позже можно только повторной авторизацией.

Дальше YouTube доступен и в чате Mira, и через MCP-сервер в Claude, Cursor или другом клиенте с поддержкой протокола.