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 или новее.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Записи вне управления плейлистами — загрузки, комментарии, оценки, подписки и изменения канала — намеренно выходят за рамки.

Настройка

Пакет 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 не заменяют последующий поток Google OAuth.

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

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

Claude Desktop

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "@youtube-mcp/server@0.4.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.4.0 serve

Codex

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

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

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

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

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

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

Таким образом, 50 песен — это максимум для создания одного плейлиста. Поскольку подготовленный черновик пока нельзя зафиксировать в существующем плейлисте, список длиннее 50 песен придётся разбить на несколько плейлистов.

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

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

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

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

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

[!WARNING] Известное ограничение: локальный реестр фиксирует каждый вызов search.list как 1 общую единицу плюс 1 поисковый вызов, тогда как Google списывает за него 100 единиц. После интенсивного поиска general_units занижает реальное потребление на 99 единиц за каждый поиск, и запись может быть отклонена из-за квоты, хотя отображаемое значение всё ещё выглядит низким. Считайте количество search_calls значимым индикатором, пока это не исправлено. В предпросмотрах по-прежнему отображается значение estimated_commit_units для части коммита, относящейся к записи.

Значения квот могут меняться. Работы по реализации и выпуску должны сверяться с актуальной официальной таблицей стоимости, а не считать значения в этом 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 не предоставляет область только для плейлистов.

• Сервер компенсирует эту широкую область 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 для локального состояния квоты/черновика/журнала и адаптер системной связки ключей для токенов обновления 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 и профили

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

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

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

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

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

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

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

Лицензия

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

Ссылки

• Model Context Protocol

• YouTube Data API v3

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

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

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

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