youtube-mcp

MCP-сервер, позволяющий анализировать YouTube-канал @ザビエル-zav напрямую из Claude. Цель — отвечать на вопросы вроде «Какое видео на прошлой неделе имело лучший CTR?», подтягивая реальные данные.

Сделан на Node.js (без Python). YouTube Analytics API / Reporting API / Data API v3 обёрнуты в официальные библиотеки для Node (googleapis, google-auth-library) и опубликованы как инструменты через официальный TypeScript SDK MCP (@modelcontextprotocol/sdk).

Используемые API и их назначение

CTR получается принципиально другим способом (bulk-отчёты), поэтому используется отдельный путь: регистрация задания через register-reach-job.js → периодическое накопление CSV локально через download-reports.js.

Related MCP server: youtube-organic-mcp

Настройка

1. Google Cloud Console

1. Создайте проект

2. Включите следующие 3 API:

   • YouTube Analytics API

   • YouTube Reporting API

   • YouTube Data API v3

3. Настройте экран согласия OAuth (тип пользователя = внешний, добавьте свой аккаунт Google в тестовые пользователи)

4. Создайте Учётные данные > OAuth-клиент ID > Тип приложения = Desktop app и скачайте JSON

5. Положите скачанный JSON в корень этого репозитория под именем client_secret.json

   Никогда не коммитьте client_secret.json и token.json, создаваемый после первой авторизации. Они уже в .gitignore, но будьте осторожны, чтобы случайно не сделать git add -f.

2. Node.js и зависимости

Нужен Node.js 18 или новее (если не установлен — поставьте LTS-версию с nodejs.org. В установщик входит и npm, так что отдельная настройка PATH, как для Python, в основном не нужна).

npm install

3. Регистрация задания для reach-отчёта (CTR) — выполнить в первую очередь

Reporting API начинает генерацию данных «с дня регистрации задания», и за прошлые периоды можно получить данные только за 30 дней до момента регистрации. Чем дольше откладывать регистрацию, тем больше исторических CTR-данных будет потеряно, поэтому выполните это раньше остальных задач.

npm run register-reach-job

При первом запуске откроется браузер и запросит авторизацию (далее — автоматическое обновление через token.json).

4. Запуск MCP-сервера

npm start

Для использования из Claude Desktop зарегистрируйте сервер в claude_desktop_config.json следующим образом.

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

5. Скачивание reach-отчётов (через несколько часов — 2 дня после регистрации)

npm run download-reports

CSV накапливаются в data/reach/<report_type>/. Отчёты удаляются на стороне YouTube через 60 дней (для исторических данных — через 30 дней), поэтому запускайте скачивание регулярно (в идеале — раз в день). На Windows можно использовать Планировщик заданий, на Mac/Linux — cron. Инструмент get_reach читает эти локальные CSV.

Список публичных инструментов

Вывод — не сырой JSON, а округлённые числа и текстовые таблицы (не более ~20 строк), чтобы экономить контекст на стороне Claude.

Известные ограничения

• Данные Analytics API отстают от показателей YouTube Studio на срок до 2 дней. «Вчерашние цифры» могут быть недоступны.

• get_reach видит только уже скачанные локально CSV. Данные за периоды, когда download-reports.js не запускался, не появятся.

• Точная структура колонок channel_reach_basic_a1 / channel_reach_combined_a1 не подтверждена. get_reach читает их с фолбэком, угадывая имена колонок по ключевым словам, но стоит один раз проверить по заголовкам реально скачанных CSV.

• Запись не поддерживается (только чтение). Пути для случайного изменения или удаления видео не существует.

Варианты развёртывания

Если нужно использовать и со смартфона, быстрее всего переключить StdioServerTransport на StreamableHTTPServerTransport (@modelcontextprotocol/sdk/server/streamableHttp.js) и разместить на существующем хостинге.