YouTube Studio MCP

MCP-сервер для аудита и улучшения находимости канала YouTube.

Он подключает любого MCP-совместимого ИИ-агента к данным вашего канала: каталогу, метрикам Analytics API, кривым удержания, входящим поисковым запросам, а также показам и рейтингу кликов, которые доступны только в CSV-экспорте Studio. Затем он ранжирует то, что стоит исправить, по восстанавливаемым просмотрам, а не по рейтингу кликов — см. Как ранжируются отстающие видео.

Восемь инструментов: auth_status, list_videos, get_video, query_analytics, get_search_terms, get_retention_curve, import_studio_data и find_underperformers.

Всё построено только на чтение и работает локально: кэш SQLite, ваши OAuth-токены и ваши экспорты Studio никогда не покидают ваш компьютер.

Требования

• Node.js ≥ 22

• Аккаунт Google, которому принадлежит YouTube-канал

Related MCP server: MCP YouTube Intelligence

Настройка

1. Создайте проект в Google Cloud и включите API

1. Перейдите на https://console.cloud.google.com/ и создайте проект.

2. Включите YouTube Data API v3 и YouTube Analytics API. (Оба активно используются: Data API обеспечивает синхронизацию каталога и работу list_videos/get_video, а Analytics API — работу query_analytics, get_search_terms и get_retention_curve. Google Cloud Console позволяет добавить область доступа на экране согласия только для включённого вами API, поэтому включите оба API до следующего шага.)

2. Настройте экран согласия OAuth

1. Перейдите в APIs и сервисы → Экран согласия OAuth.

2. Выберите Внешние и заполните обязательные поля.

3. Добавьте следующие области доступа:

   • https://www.googleapis.com/auth/yt-analytics.readonly

   • https://www.googleapis.com/auth/youtube.readonly

   • https://www.googleapis.com/auth/youtube.force-ssl

Важно — опубликуйте приложение в Production. Пока приложение находится в статусе Testing, Google отзывает refresh-токены через 7 дней, поэтому вам придётся проходить аутентификацию каждую неделю. Нажмите Publish app. Приложение останется unverified, и это нормально: вы единственный пользователь и обращаетесь к собственным данным. Предупреждение «непроверенное приложение» появится один раз — выберите Advanced → Go to (app name).

3. Создайте OAuth-клиент

1. APIs и сервисы → Credentials → Create credentials → OAuth client ID.

2. Application type: Desktop app.

3. Скачайте JSON-файл.

4. Установка и аутентификация

npm install
npm run build

Сохраните скачанный JSON OAuth-клиента как credentials.json в конфигурационном каталоге сервера (если его нет, сначала создайте его):

# Linux/macOS — adjust the source filename to match what Google actually
# named your download (it starts with "client_secret_")
mkdir -p ~/.config/youtube-studio-mcp
mv ~/Downloads/client_secret_*.json ~/.config/youtube-studio-mcp/credentials.json

# Windows (PowerShell) — same caveat about the source filename
New-Item -ItemType Directory -Force "$env:USERPROFILE\.config\youtube-studio-mcp" | Out-Null
Move-Item "$env:USERPROFILE\Downloads\client_secret_*.json" "$env:USERPROFILE\.config\youtube-studio-mcp\credentials.json"

Затем выполните:

node dist/index.js auth

После этого автоматически откроется браузер. Авторизуйтесь в нём, и токены будут сохранены в <config dir>/tokens.json. В Linux/macOS файл записывается с правами только для владельца (chmod 600); в Windows нет аналогичных битов прав доступа, поэтому там этот шаг пропускается — достаточно обычных файловых защит вашей учётной записи.

Если браузер не открылся, команда также записывает ссылку для авторизации в <config dir>/authorize-url.txt — откройте этот файл и перейдите по ссылке. Не копируйте URL вручную из терминала: его длина — ~520 символов, он переносится на несколько строк, и усечённая копия приводит к ошибке Google с вводящим в заблуждение сообщением Required parameter is missing: response_type (отсутствующий параметр находится в обрезанной части, а не в том запросе, который собираем мы).

Установите переменную YTMCP_HOME, чтобы переопределить конфигурационный каталог (например, для второго канала или тестовой настройки). Она заменяет весь путь ~/.config/youtube-studio-mcp, поэтому credentials.json, tokens.json и кэш SQLite перемещаются вместе с ней.

5. Подключите сервер к вашему ИИ-агенту

Сервер работает по стандартному MCP через stdio, поэтому его может запустить любой MCP-совместимый клиент. В каждом случае вам понадобится одна вещь: абсолютный путь к dist/index.js в этом репозитории.

Большинство клиентов используют одну и ту же JSON-структуру. Подставьте собственный путь:

{
  "mcpServers": {
    "youtube-studio": {
      "command": "node",
      "args": ["/absolute/path/to/youtube-studio-mcp/dist/index.js"]
    }
  }
}

Два клиента используют другой формат.

VS Code / GitHub Copilot — .vscode/mcp.json, где используется ключ servers, а не mcpServers:

{
  "servers": {
    "youtube-studio": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/youtube-studio-mcp/dist/index.js"]
    }
  }
}

OpenAI Codex CLI — ~/.codex/config.toml, в формате TOML, а не JSON:

[mcp_servers.youtube-studio]
command = "node"
args = ["/absolute/path/to/youtube-studio-mcp/dist/index.js"]

Перезапустите агента после изменения его конфигурации. Попросите его выполнить auth_status: он должен назвать ваш канал и сообщить об оставшейся квоте. Если он сообщит Authenticated: NO, заново выполните node dist/index.js auth.

Если вашего клиента здесь нет, поищите «MCP» в его настройках — команда и аргументы, указанные выше, подходят любому из них. Пути к конфигурационным файлам могут меняться от версии к версии, поэтому проверяйте документацию вашего клиента, если указанного пути не существует.

Замечание о поведении агентов

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

list_videos берёт данные из локального кэша, если только вы не попросите синхронизацию, а find_underperformers и import_studio_data вообще никогда не обращаются к сети. Квоту расходуют только явные синхронизации и запросы к Analytics; это важно, поскольку агенты активно исследуют: 20 вызовов list_videos ничего не стоят, а 20 синхронизаций каталога могут исчерпать дневной лимит. Текущее количество оставшейся квоты сообщает auth_status.

Инструменты

list_videos полностью работает из локального кэша SQLite, если вы не передаёте sync: true — обычные чтения (фильтрация по Shorts/длинным видео, числу просмотров, дате публикации, названию или сортировка) не расходуют квоту. Если ещё ничего не синхронизировано, инструмент попросит вызвать его снова с sync: true, а не вернёт пустой список.

get_search_terms и get_retention_curve кэшируют свои результаты в каждом окне дат (см. раздел «Квота» ниже); query_analytics не кэширует ничего и всегда выполняет «живой» вызов. get_search_terms возвращает не более 25 строк — Google ограничивает базовый отчёт, поэтому более широкий диапазон дат изменяет не количество возвращаемых строк, а то, какие термины попадают в топ-25.

Квота

YouTube даёт 10 000 единиц в день плюс отдельные 100 вызовов search.list в день. Сервер отслеживает и то, и другое, а также держит резерв (500 единиц и 10 поисковых вызовов), чтобы массовая операция не сделала интерактивные инструменты бесполезными. Квота сбрасывается в полночь по тихоокеанскому времени, — именно это отражает auth_status.

Полная синхронизация каталога (list_videos с sync: true) выполняет один вызов channels.list, затем постранично проходит плейлист загрузок (playlistItems.list, 50 видео на страницу) и получает детали видео в пачках (videos.list, 50 ID на вызов), каждый из которых стоит 1 единицу. Итого выходит 1 + ceil(videos/50) + ceil(videos/50) единиц — около 5 единиц для канала со 100 видео.

У Analytics API есть своя квота на проект в Cloud Console, которая не связана с 10 000 единиц Data API. Обращение к Analytics записывается в локальный журнал с нулевой стоимостью в единицах, поэтому auth_status не покажет их как расходующие ваш бюджет Data API.

Результаты поисковых запросов и кривые удержания кэшируются для каждого окна дат, потому что соответствующие отчёты возвращаютранжевый топ-N за период, а не строки по отдельным дням. Повторный вызов с теми же датами берётся из кэша; передайте refresh: true, чтобы выполнить повторный запрос.

Импорт данных о показах и CTR

impressions и impressionClickThroughRate не существуют в YouTube Analytics API — они доступны только в Studio. Чтобы их получить:

1. YouTube Studio → Analytics → Advanced mode (в правом верхнем углу)

2. Убедитесь, что колонки Impressions и Impressions click-through rate видны — в экспорт попадают только те колонки, которые сейчас на экране

3. Export → Comma-separated values (.csv) — вы получите ZIP-архив с тремя файлами

4. Распакуйте его, затем запустите import_studio_data с путём к папке

import_studio_data только читает файл с диска — он никогда не вызывает YouTube Data API или Analytics API, поэтому ему не нужна аутентификация и он не тратит квоту.

Окно дат берётся из имени папки (Studio называет её в формате Contenido 2010-01-26_2026-08-09 Channel). Чтобы переопределить его, передайте оба параметра rangeStart и rangeEnd (YYYY-MM-DD) — передача только одного будет отклонена ошибкой валидации, а не молчаливо использует окно из имени папки, потому что в противном случае данные могут попасть под неправильные даты без какого-либо предупреждения. Обе даты должны быть реальными календарными (2026-13-45 станет причиной отклонения, а не будет перенесено на следующую дату), и rangeStart не должен идти после rangeEnd.

Показы и CTR — это агрегат за весь диапазон. Из трех файлов в экспорте только таблица по видео (Datos de la tabla.csv / Table data.csv) содержит показы и CTR, и в ней одна строка на видео, суммированная за весь диапазон дат — в экспорте нет дневного CTR. Файл по дням (Datos del gráfico.csv / Chart data.csv) и файл с итогами по каналу (Totales.csv / Totals.csv) содержат только просмотры. Поэтому сравнение во времени означает импорт нескольких экспортов с разными диапазонами, а не нарезку одного.

import_studio_data принимает либо папку экспорта, либо конкретный путь к CSV. Укажите на папку — и он автоматически найдет таблицу. Укажите напрямую на один из двух других файлов — и импорт будет отклонен сразу: заголовок CSV однозначно говорит, какой из трех отчетов перед вами (reportType — это table, chart или totals; см. src/studio/csvSchemas.ts), и только table содержит что-то, что этот импортер может сохранить. В файле графика есть идентификатор видео, поэтому наивный импорт молча бы прошел, перезаписав показы/CTR на NULL, а просмотры — на значение последнего дня вместо суммы за диапазон; в файле итогов вообще нет идентификатора видео. Оба отклоняются до записи чего-либо, с сообщением, указывающим на Datos de la tabla.csv / Table data.csv как на файл, на который следует указывать.

Строки для видео, которые больше не являются публичными, сохраняются и сообщаются как несоответствующие; это ожидаемо, а не ошибка.

Shorts

Видео считается Short только если оно 180 секунд или короче и было опубликовано 14 сентября 2020 года или позже — в день запуска Shorts.

Одной длительности недостаточно. В каталоге естественно коротких длинных видео — музыкальных клипов, нарезок, трейлеров — правило, основанное только на длительности, ошибочно классифицирует всё подряд. Живая проверка на неактивном канале до 2020 года пометила примерно 70% его каталога как Shorts, и каждый был ложноположительным: самая новая загрузка канала была опубликована за месяцы до запуска Shorts, так что ни одно из них не могло быть настоящим.

find_underperformers читает этот флаг через параметр cohort. Передача cohort: 'short' или cohort: 'long' ограничивает базовую линию этой половиной каталога, так что Shorts и длинные видео сравниваются только со своими. По умолчанию cohort: 'all' не выполняет такое сегментирование — он объединяет обе группы в единую смешанную базовую линию. В каталоге, который уже является одной когортой (реальный случай этого пользователя — полностью длинные видео), объединение не имеет эффекта, но в смешанном каталоге по умолчанию смешивает две популяции с разными типичными CTR; передайте cohort явно, чтобы сегментировать их. Неправильный флаг на видео дал бы уверенную бессмыслицу, а не очевидную ошибку, поэтому проверка даты публикации важна.

Как ранжируются неэффективные видео

find_underperformers ранжирует по восстановимым просмотрам, а не по рейтингу кликов:

recoverable views = impressions x (baseline CTR - video CTR) / 100

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

• Показы концентрируются. Большая часть показов канала приходится на небольшую долю его видео, поэтому «худший CTR» и «самая большая возможность» — почти непересекающиеся множества. Видео с самым уродливым соотношением часто почти никому не показывали.

• Ноль показов дает 0% CTR по делению, а не по эффективности. Сортировка по возрастанию ставит каждое никогда не показанное видео в начало списка того, что нужно исправить, что ровно наоборот.

• Самый высокий CTR на канале — это обычно крошечный знаменатель — горстка показов, которые случайно конвертировались. Это шум, представленный как триумф.

Отсюда следуют два правила. Видео ниже порога показов сообщаются как недостаточно данных и никогда не ранжируются как слабые исполнители. А базовая линия взвешена по показам, потому что невзвешенное среднее доминируется низкотрафиковыми видео и описывает почти ни одного из трафика, который канал реально получает.

Каждая возможность типизирована. weak_metadata означает, что оценка метаданных достаточно низкая, и это то, что нужно исправить в первую очередь; low_ctr означает, что метаданные уже в порядке, и рычагом является миниатюра или формулировка заголовка.

Разработка

npm test          # unit tests, no network
npm run typecheck
npm run build

npm run typecheck запускает два проекта: tsconfig.json (src/**, сборка) и tsconfig.test.json (src/** + test/** + vitest.config.ts, только noEmit). Запустите только тестовый проект с помощью npm run typecheck:test. Сам Vitest только удаляет типы через esbuild и не выполняет проверку типов, поэтому npm run typecheck — это то, что действительно ловит ошибку типа в тестовом файле.