YouTube MCP Server

Сервер Model Context Protocol (MCP) с открытым исходным кодом для использования YouTube из MCP-клиентов, таких как Claude Desktop, Claude Code и Codex.

Основной рабочий процесс:

1. Передайте MCP-клиенту список песен.

2. Просмотрите ранжированные совпадения YouTube, прежде чем что-либо менять.

3. Создайте приватный плейлист из выбранных видео.

Сервер также предоставляет инструменты, экономящие квоту, для поиска по YouTube и чтения видео, каналов, плейлистов и комментариев.

[!IMPORTANT] TypeScript-пакет, stdio-сервер, публичные и аутентифицированные чтения, PKCE OAuth, подготовка музыки, подтверждённое создание нового плейлиста и полные изменения плейлиста с предпросмотром реализованы и протестированы. Подготовленный музыкальный черновик можно зафиксировать в новом плейлисте или добавить в существующий принадлежащий вам плейлист.

Цели проектирования

• Безопасные записи в плейлисты с семантикой предпросмотра перед фиксацией.

• Только официальные конечные точки YouTube Data API v3.

• Собственный Google OAuth-клиент; проект никогда не поставляет общие учётные данные Google.

• Секреты хранятся в связке ключей операционной системы, когда это возможно.

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

• Локальный транспорт stdio для простой установки и небольшой поверхности атаки.

• Структурированные, ограниченные выходные данные инструментов, которые рассматривают контент YouTube как ненадёжные данные.

• Кроссплатформенная поддержка TypeScript на Node.js 20.17 или новее.

Related MCP server: youtube-music-mcp

Планируемый объём v1

Инструменты чтения

• Поиск видео, каналов и плейлистов.

• Чтение данных видео, каналов, плейлистов и комментариев.

• Чтение канала, загрузок и плейлистов аутентифицированного пользователя.

• Возврат токенов страниц провайдера для явной пагинации без сохранения состояния.

Рабочий процесс музыкальных плейлистов

• Принимать до 50 структурированных треков за один запрос подготовки.

• Искать и ранжировать вероятные совпадения музыкальных видео YouTube.

• Показывать неоднозначность и альтернативы вместо молчаливого выбора слабых совпадений.

• Фиксировать явно выбранные совпадения в новом плейлисте или существующем принадлежащем плейлисте.

• По умолчанию новые плейлисты — private.

Управление комментариями

• Публикация комментария верхнего уровня к видео или ответ на существующий комментарий.

• Удаление комментария или установка его статуса модерации — за предпросмотром и одноразовым дескриптором.

• Использует область youtube.force-ssl, уже запрашиваемую для записи плейлистов, поэтому дополнительное согласие не требуется.

Управление плейлистами

• Создание плейлистов и добавление видео.

• Обновление метаданных плейлиста или уровня приватности.

• Изменение порядка или удаление элементов плейлиста.

• Удаление плейлистов после выдачи кратковременного одноразового дескриптора подтверждения.

Обновления плейлистов, удаление/изменение порядка элементов и удаление используют два инструмента: youtube_prepare_playlist_mutation возвращает точный diff и дескриптор на 10 минут без записи; youtube_apply_playlist_mutation повторно проверяет право собственности и снимок плейлиста перед одноразовым использованием этого дескриптора.

Загрузка видео и жизненный цикл

• Загрузка локального видеофайла через возобновляемую загрузку, по умолчанию private.

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

• Установка пользовательской миниатюры из локального JPEG или PNG.

• Предпросмотр, а затем окончательное удаление видео, которым вы владеете.

Запись видео требует дополнительной области youtube.upload и категорически отказывается работать, если профиль был авторизован без неё. youtube_plan_video_upload проверяет файл и сообщает стоимость без обращения к YouTube, поскольку videos.insert стоит 1600 единиц — около 16% стандартного дневного бюджета за одну загрузку. Загрузка никогда не повторяется: если результат неизвестен, об этом сообщается, чтобы вы могли проверить частичную загрузку вместо публикации дубликата.

Управление плейлистами, комментариями и видео — это реализованные поверхности записи. Отчётность по аналитике (0.8) находится в дорожной карте и пока недоступна для вызова. Оценки, подписки и запись настроек канала навсегда остаются вне области действия.

Настройка

Пакет npm ещё не опубликован, поэтому сервер собирается и запускается из клона. Выполните шаги по порядку.

Шаг 1 — проверьте наличие Node.js и npm

node -v
npm -v

Если node -v выводит v20.17 или новее, а npm -v выводит версию, перейдите к Шагу 3. Если любая из команд сообщает «command not found», продолжайте с Шага 2.

Шаг 2 — установите Node.js и npm (только если Шаг 1 не удался)

npm поставляется вместе с Node.js; установка Node устанавливает оба. Выберите одну строку для вашей платформы, затем повторно выполните Шаг 1 для подтверждения.

Если вы не хотите устанавливать Node в систему или вам нужно несколько версий Node рядом, используйте менеджер версий:

# macOS and Linux
curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install 22
nvm use 22

В Windows аналог — nvm-windows: nvm install 22, затем nvm use 22.

Закройте и снова откройте терминал после установки, затем повторно выполните node -v и npm -v.

Шаг 3 — установите зависимости и соберите

git clone <repository-url>
cd "Youtube MCP"
npm ci
npm run build

npm ci устанавливает точные версии из package-lock.json; используйте npm install только если намерены изменить зависимости. Сборка записывает исполняемый файл в dist/cli/index.js, который вызывается всеми командами ниже.

Проверьте сборку и локальный каталог данных:

node dist/cli/index.js doctor

Шаг 4 — создайте учётные данные Google

Всё ниже исходит из вашего собственного проекта Google Cloud. Этот проект никогда не поставляет общие учётные данные Google.

1. Создайте или выберите проект в консоли Google Cloud.

2. Включите YouTube Data API v3 для этого проекта.

3. Создайте API-ключ (Credentials → Create credentials → API key). Он покрывает публичные чтения.

4. Настройте экран согласия OAuth. Пока проект находится в статусе Testing, добавьте свой аккаунт Google в раздел Test users, иначе login будет отклонён.

5. Создайте OAuth-клиент типа Desktop app, затем скопируйте и его client ID, и client secret.

Google требует client_secret при обмене кода авторизации даже для установленных приложений, поэтому PKCE здесь дополняет секрет, а не заменяет его.

Шаг 5 — учётные данные, необходимые серверу

Всего существует четыре учётных данных. Первые три предоставляете вы; четвёртые получаются для вас командой login.

Необязательные переменные окружения: YOUTUBE_MCP_PROFILE (по умолчанию default), YOUTUBE_MCP_DATA_DIR и YOUTUBE_MCP_LOG_LEVEL (error, warn, info, debug). См. .env.example.

Никогда не вставляйте ни одно из этих значений в сообщение чата, общий файл конфигурации MCP или команду, которая будет зафиксирована. Предпочитайте интерактивные запросы или поле ввода окружения/секретов вашего клиента.

Шаг 6 — запустите setup, затем войдите

Выполните их по порядку. setup перезаписывает сохранённые области и идентичность канала профиля, поэтому запуск его после login отбрасывает это состояние и требует повторного входа.

macOS и Linux:

YOUTUBE_OAUTH_CLIENT_ID="YOUR_DESKTOP_CLIENT_ID" \
  YOUTUBE_OAUTH_CLIENT_SECRET="YOUR_DESKTOP_CLIENT_SECRET" \
  node dist/cli/index.js setup
node dist/cli/index.js login
node dist/cli/index.js status

Windows PowerShell:

$env:YOUTUBE_OAUTH_CLIENT_ID  = "YOUR_DESKTOP_CLIENT_ID"
$env:YOUTUBE_OAUTH_CLIENT_SECRET = "YOUR_DESKTOP_CLIENT_SECRET"
node dist\cli\index.js setup
node dist\cli\index.js login
node dist\cli\index.js status
Remove-Item Env:\YOUTUBE_OAUTH_CLIENT_SECRET

Чтобы вообще не помещать секрет в историю оболочки или таблицу процессов, опустите обе переменные и позвольте setup запросить их:

node dist/cli/index.js setup

setup запрашивает каждое отсутствующее значение, когда терминал интерактивен.

login открывает страницу авторизации Google и возвращается через случайный порт loopback на 127.0.0.1, используя PKCE S256 и случайное значение state. Он немедленно завершается с ошибкой, до открытия браузера, если для профиля не сохранён client secret.

Чтобы отозвать и удалить сохранённые учётные данные:

node dist/cli/index.js logout

Шаг 7 — запустите сервер

YOUTUBE_API_KEY="your-api-key" node dist/cli/index.js serve

Сервер говорит по MCP через stdio, поэтому обычно он запускается клиентом, а не вручную. Доступные команды: serve, doctor, status, setup, login и logout.

Расположение локальных данных

Профили, реестр квот, черновики и журналы операций находятся в каталоге с правами 0700:

Переопределяется с помощью YOUTUBE_MCP_DATA_DIR. Чтобы удалить всё локальное состояние, выполните logout, а затем удалите этот каталог. Записи в связке ключей удаляются командой logout.

Подключение клиента к локальной сборке

Пока пакет не опубликован, указывайте клиентам на абсолютный путь вашего собранного dist/cli/index.js.

Claude Code

claude mcp add youtube --scope user \
  --env YOUTUBE_MCP_PROFILE=default \
  --env YOUTUBE_API_KEY=your-api-key -- \
  node /absolute/path/to/Youtube\ MCP/dist/cli/index.js serve

Claude Desktop

{
  "mcpServers": {
    "youtube": {
      "command": "node",
      "args": ["/absolute/path/to/Youtube MCP/dist/cli/index.js", "serve"],
      "env": {
        "YOUTUBE_MCP_PROFILE": "default",
        "YOUTUBE_API_KEY": "your-api-key"
      }
    }
  }
}

Codex

[mcp_servers.youtube]
command = "node"
args = ["/absolute/path/to/Youtube MCP/dist/cli/index.js", "serve"]

[mcp_servers.youtube.env]
YOUTUBE_MCP_PROFILE = "default"
YOUTUBE_API_KEY = "your-api-key"

Повторно выполните npm run build после получения изменений; клиенты выполняют скомпилированный вывод dist, а не src.

Авторизация Google для этого локального сервера выполняется его собственными командами setup и login. Команды входа MCP на уровне клиента не заменяют последующий поток OAuth Google.

Конфигурация клиента после публикации

После выпуска пакета закрепите выпущенную версию вместо использования latest, чтобы MCP-клиент не мог неожиданно изменить поведение.

Claude Desktop

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "@youtube-mcp/server@0.7.0", "serve"],
      "env": {
        "YOUTUBE_MCP_PROFILE": "default"
      }
    }
  }
}

В нативном Windows используйте "command": "cmd" и добавьте префикс "/c", "npx" к аргументам.

Claude Code

claude mcp add youtube --scope user \
  --env YOUTUBE_MCP_PROFILE=default -- \
  npx -y @youtube-mcp/server@0.7.0 serve

Codex

codex mcp add youtube \
  --env YOUTUBE_MCP_PROFILE=default -- \
  npx -y @youtube-mcp/server@0.7.0 serve

Эквивалентная конфигурация Codex:

[mcp_servers.youtube]
command = "npx"
args = ["-y", "@youtube-mcp/server@0.7.0", "serve"]

[mcp_servers.youtube.env]
YOUTUBE_MCP_PROFILE = "default"

Сколько можно добавить за один раз

Жёсткие ограничения схемы на один вызов инструмента:

Таким образом, 50 песен — это потолок для одного коммита. Более длинный список обрабатывается пакетами по 50: плейлист создаётся с первым пакетом, затем его target_playlist_id передаётся в каждый последующий коммит для добавления. Уже присутствующие дубликаты пропускаются и сообщаются, а не вставляются дважды.

Ежедневная квота на практике является более жёстким ограничением. При стандартных 10 000 единиц Google на проект в день, один прогон на 50 песен стоит примерно:

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

Квота сбрасывается в полночь по тихоокеанскому времени США, что является границей дня, которую использует локальный реестр.

Ожидания по квоте

youtube_quota_status сообщает о локально наблюдаемом использовании, а не об авторитетном балансе Google. Общие единицы и вызовы search.list отслеживаются отдельно, поскольку Google применяет отдельный стандартный дневной лимит на поисковые вызовы.

search.list тарифицируется по опубликованным 100 единицам, поэтому general_units отражает реальное потребление. Релизы до 0.5.0 записывали его как 1 единицу и, следовательно, занижали использование на 99 единиц за каждый поиск; запись могла быть отклонена из-за квоты, в то время как отчётная цифра всё ещё выглядела низкой. Обновитесь, если вы используете более раннюю сборку.

Значения квот могут меняться. Работа по реализации и выпуску должна проверять текущую официальную таблицу стоимости, а не рассматривать значения в этом README как постоянные константы.

Устранение неполадок

Коммит сообщает status: "partial" с пустым completed и всем в pending. Плейлист был создан, но первая вставка была отклонена — чаще всего из-за дневной квоты. Ничего не повторяется вслепую, поэтому дублирующиеся элементы не записываются. Проверьте youtube_quota_status, удалите пустой плейлист и повторите запуск после сброса по тихоокеанскому времени. Поскольку черновик одноразовый, для повторного запуска требуется новый youtube_prepare_music_playlist.

login завершается ошибкой до открытия браузера. Для профиля не сохранён секрет клиента. Сначала запустите setup и убедитесь, что вы находитесь в нужном YOUTUBE_MCP_PROFILE.

Авторизация проходит успешно, но перестаёт работать примерно через неделю. Проекты Google OAuth, оставленные в статусе Testing, выдают токены обновления, срок действия которых истекает через семь дней. Опубликуйте экран согласия или повторно запустите login.

403 при публичном чтении. YOUTUBE_API_KEY отсутствует в окружении сервера. Он никогда не сохраняется, поэтому должен присутствовать при каждом запуске — включая блок env конфигурации MCP-клиента.

Модель аутентификации

• Для публичного чтения требуется YOUTUBE_API_KEY в окружении процесса.

• Для чтения аккаунта требуется OAuth с областью youtube.readonly.

• Создание плейлистов и запись комментариев требуют youtube.force-ssl, поскольку Google не предоставляет область только для плейлистов.

• Загрузка видео и управление жизненным циклом требуют youtube.upload. Он запрашивается отдельно, и видеоиструменты отказывают, когда профиль был авторизован без него. Добавьте его на экран согласия и повторно запустите login перед загрузкой.

• Сервер противодействует этой широкой области Google строгим списком разрешённых конечных точек: доступны только конечные точки записи плейлистов и элементов плейлистов.

• Установленные приложения используют Authorization Code + PKCE, случайный state и loopback-редирект на 127.0.0.1 со случайным портом.

• Сервисные аккаунты не поддерживаются для обычных аккаунтов YouTube.

Никогда не коммитьте API-ключи, данные OAuth-клиента, токены доступа, токены обновления, локальные базы данных, журналы отладки или файлы .env.

Субтитры и аналитика

Общее получение публичных транскриптов не входит в v1. Официальная конечная точка загрузки субтитров ограничена правами и дорога, поэтому неофициальный скрапинг использоваться не будет. Управление субтитрами с авторизацией владельца может быть рассмотрено позже.

API YouTube Analytics и Reporting также отложены. Они требуют отдельного OAuth, моделей данных и операционного поведения и не должны усложнять изначальный сервер, ориентированный на плейлисты.

Разработка

Реализованный стек: TypeScript, Node.js 20.17+, ESM, официальный MCP TypeScript SDK, валидация Zod, прямые типизированные REST-вызовы к одобренным конечным точкам Google, SQLite для локального состояния квоты/черновика/журнала и адаптер OS-keychain для OAuth-токенов обновления.

Текущие проверки:

npm run format:check
npm run lint
npm run typecheck
npm test
npm run build

Реализация должна следовать фазам и приёмочным критериям в PLAN.md. Ограничения и определения готовности для агентов находятся в AGENTS.md. Claude Code следует начинать с CLAUDE.md.

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

• Архитектура продукта и безопасности

• Инструкции по разработке репозитория

• Каркас TypeScript-пакета

• Инструменты публичного чтения

• OAuth и профили

• Сопоставление музыки и предпросмотр

• Подтверждённое создание нового плейлиста

• Предпросмотренное обновление, переупорядочивание, удаление и стирание плейлиста

• Целевой существующий плейлист для коммитов музыкальных черновиков (0.5)

• Корректный учёт общих единиц search.list в реестре квот (0.5)

• Вставка, ответ, удаление и модерация комментариев (0.6)

• Загрузка видео, обновление метаданных, удаление и миниатюры (0.7)

• Отчётность YouTube Analytics (0.8)

• Кросс-клиентские интеграционные тесты

• Первый npm-релиз

Лицензия

Лицензировано по Apache License 2.0. Полный текст лицензии находится в LICENSE.

Ссылки

• Model Context Protocol

• YouTube Data API v3

• Стоимость квот YouTube Data API

• Google OAuth для установленных приложений

• Документация Claude MCP

• Документация Codex MCP