YouTube MCP Server

MCP-сервер, который подключает YouTube к Claude Code: транскрипты видео, поиск, метаданные, информация о каналах, плейлисты, комментарии, популярные видео, аналитика вовлечённости, извлечение глав, интеграция SponsorBlock и тепловые карты самых пересматриваемых моментов. Использует YouTube Data API v3, youtube-transcript и SponsorBlock.

Быстрый старт

Шаг 1: Получите API-ключ

1. Перейдите в Google Cloud Console

2. Создайте проект (или выберите существующий)

3. Включите YouTube Data API v3:

   • Перейдите в Библиотеку API

   • Нажмите Включить

4. Создайте API-ключ:

   • Перейдите в Учётные данные

   • Нажмите Создать учётные данные > API-ключ

5. Скопируйте ключ (он понадобится вам на шаге 3)

Шаг 2: Установите предварительные требования

• Node.js 18+ — Скачать

• Claude Code CLI — Руководство по установке

Шаг 3: Установите MCP-сервер

3.1 Клонируйте репозиторий

git clone https://github.com/wynandw87/claude-code-youtube-mcp.git
cd claude-code-youtube-mcp

3.2 Установите зависимости

macOS / Linux / Windows:

npm install

Примечание: Зависимости устанавливаются и сервер автоматически собирается за один шаг.

3.3 Зарегистрируйте сервер в Claude Code

Выберите область установки:

Замените YOUR_API_KEY на ваш реальный ключ YouTube Data API и укажите полный путь к dist/index.js.

Совет: Чтобы получить полный путь, выполните эту команду из клонированного каталога:

• macOS/Linux: echo "$(pwd)/dist/index.js"

• Windows: echo %cd%\dist\index.js

macOS / Linux:

claude mcp add -s user youtube -e YOUTUBE_API_KEY=YOUR_API_KEY -- node /full/path/to/dist/index.js

Windows (CMD):

claude mcp add -s user youtube -e "YOUTUBE_API_KEY=YOUR_API_KEY" -- node "C:\full\path\to\dist\index.js"

Windows (PowerShell):

claude mcp add -s user youtube -e "YOUTUBE_API_KEY=YOUR_API_KEY" '--' node "C:\full\path\to\dist\index.js"

Альтернатива: использование npm-хелпера (если API-ключ задан в окружении)

export YOUTUBE_API_KEY=YOUR_API_KEY
npm run install:claude

Шаг 4: Перезапустите Claude Code

Закройте и снова откройте Claude Code, чтобы изменения вступили в силу.

Шаг 5: Проверьте установку

claude mcp list

Вы должны увидеть youtube в списке со статусом Connected.

Related MCP server: youtube-research

Возможности

Транскрипты и субтитры

• Получить транскрипт (get_transcript) — получить полный транскрипт видео с таймкодами, поддерживается несколько языков

• Поиск по транскрипту (search_transcript) — найти, где в видео встречается ключевое слово или фраза, с таймкодами

• Чистый транскрипт (get_clean_transcript) — транскрипт без рекламных интеграций, интро, аутро и посторонних вставок через SponsorBlock

• Извлечение глав (extract_chapters) — разбор таймкодов глав из описания видео

Поиск и обнаружение

• Поиск видео (search_videos) — полный поиск по YouTube с фильтрами по дате, длительности, типу и порядку сортировки

• Поиск по каналу (search_within_channel) — поиск видео у конкретного автора

• Популярные видео (get_trending_videos) — текущие тренды по региону и категории

• Видео канала (get_channel_videos) — последние видео канала, отсортированные по дате или просмотрам

Информация о видео и канале

• Метаданные видео (get_video_metadata) — название, описание, длительность, просмотры, лайки, теги и другое

• Информация о канале (get_channel_info) — количество подписчиков, количество видео, описание, страна

• Элементы плейлиста (get_playlist_items) — все видео плейлиста с позициями и метаданными

Аналитика и вовлечённость

• Расчёт вовлечённости (calculate_engagement) — процент лайков, процент комментариев и уровень вовлечённости на основе открытых данных

• Самые пересматриваемые (get_most_replayed) — данные тепловой карты, показывающие, какие фрагменты зрители пересматривают чаще всего

• Комментарии к видео (get_video_comments) — лучшие комментарии с количеством лайков и ответов

Утилиты

• Разбор YouTube-URL (parse_youtube_url) — извлечение ID видео, канала или плейлиста из URL любого формата

Использование

После установки используйте фразы-триггеры для вызова инструментов YouTube:

Или спросите естественно:

• "Получи транскрипт этого видео YouTube и сделай краткое изложение"

• "Какие фрагменты этого видео пересматривают чаще всего?"

• "Найди на этом канале последние видео о TypeScript"

• "Сколько просмотров и лайков у этого видео?"

• "Получи комментарии к этому видео и опиши общую тональность"

• "Покажи главы этого обучающего видео"

• "Получи чистый транскрипт без рекламных вставок"

• "Что сейчас в тренде на YouTube в игровой категории?"

Справочник по инструментам

parse_youtube_url

Разбирает URL YouTube любого формата и извлекает идентификаторы. API-ключ не требуется.

Параметры:

• url (string, required) — любой YouTube URL или ID видео

Поддерживаемые форматы: youtube.com/watch?v=, youtu.be/, /shorts/, /embed/, /playlist?list=, /channel/, /@handle, /c/, /user/, а также ID видео без URL

get_transcript

Получает полный транскрипт/субтитры видео YouTube. API-ключ не требуется.

Параметры:

• url (string, required) — URL видео YouTube или ID видео

• lang (string, optional) — код языка субтитров (по умолчанию: "en")

search_transcript

Ищет ключевое слово или фразу в транскрипте видео.

Параметры:

• url (string, required) — URL видео YouTube или ID видео

• query (string, required) — ключевое слово или фраза для поиска

• lang (string, optional) — код языка субтитров (по умолчанию: "en")

extract_chapters

Извлекает таймкоды глав из описания видео.

Параметры:

• url (string, required) — URL видео YouTube или ID видео

get_clean_transcript

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

Параметры:

• url (string, required) — URL видео YouTube или ID видео

• lang (string, optional) — код языка субтитров (по умолчанию: "en")

get_most_replayed

Получает данные тепловой карты "самые пересматриваемые моменты", показывающей, какие фрагменты зрители пересматривают чаще всего.

Параметры:

• url (string, required) — URL видео YouTube или ID видео

Примечание: Для наличия данных тепловой карты требуется примерно 50K+ просмотров.

search_videos

Ищет по YouTube с полной поддержкой фильтров.

Параметры:

• query (string, required) — поисковый запрос

• max_results (number, optional) — количество результатов, 1–50 (по умолчанию: 10)

• order (string, optional) — "relevance", "date", "viewCount", "rating" (по умолчанию: "relevance")

• duration (string, optional) — "short" (<4 мин), "medium" (4–20 мин), "long" (>20 мин)

• upload_date (string, optional) — "hour", "day", "week", "month", "year"

• type (string, optional) — "video", "channel", "playlist" (по умолчанию: "video")

get_video_metadata

Получает подробные метаданные видео YouTube.

Параметры:

• url (string, required) — URL видео YouTube или ID видео

Возвращает: название, описание, канал, длительность, количество просмотров/лайков/комментариев, теги, категорию, миниатюры, статус трансляции и другое.

get_channel_info

Получает информацию о канале YouTube.

Параметры:

• url (string, required) — URL канала YouTube, @handle или ID канала

Возвращает: название, описание, количество подписчиков/видео/просмотров, страну, пользовательский URL и миниатюру.

get_playlist_items

Получает все видео из плейлиста YouTube.

Параметры:

• url (string, required) — URL плейлиста YouTube или ID плейлиста

• max_results (number, optional) — количество элементов, 1–50 (по умолчанию: 25)

get_channel_videos

Получает последние видео с канала YouTube.

Параметры:

• url (string, required) — URL канала YouTube, @handle или ID канала

• max_results (number, optional) — количество видео, 1–50 (по умолчанию: 25)

• order (string, optional) — "date", "viewCount" (по умолчанию: "date")

get_trending_videos

Получает текущие популярные видео YouTube.

Параметры:

• region_code (string, optional) — код страны ISO 3166-1 alpha-2 (по умолчанию: "US")

• category_id (string, optional) — ID категории YouTube (например, "10" — Музыка, "20" — Игры, "28" — Наука и техника)

• max_results (number, optional) — количество результатов, 1–50 (по умолчанию: 10)

search_within_channel

Ищет видео в пределах конкретного канала YouTube.

Параметры:

• url (string, required) — URL канала YouTube, @handle или ID канала

• query (string, required) — поисковый запрос

• max_results (number, optional) — количество результатов, 1–50 (по умолчанию: 10)

get_video_comments

Получает комментарии верхнего уровня к видео YouTube.

Параметры:

• url (string, required) — URL видео YouTube или ID видео

• max_results (number, optional) — количество комментариев, 1–100 (по умолчанию: 20)

• order (string, optional) — "relevance", "time" (по умолчанию: "relevance")

calculate_engagement

Рассчитывает показатели вовлечённости для видео YouTube.

Параметры:

• url (string, required) — URL видео YouTube или ID видео

Возвращает: количество просмотров, лайков, комментариев, процент лайков, процент комментариев и общий уровень вовлечённости.

Как это работает

Этот MCP-сервер подключается к Claude Code через stdio-транспорт и предоставляет 15 инструментов:

Примечание: 5 инструментов работают без API-ключа (транскрипты, SponsorBlock, тепловые карты, разбор URL). Оставшимся 10 требуется ключ YouTube Data API v3.

Конфигурация

Переменные окружения

Квота YouTube API

У YouTube Data API v3 есть суточная квота 10 000 единиц. Каждый инструмент расходует разное количество:

Совет: Поисковые операции — самые дорогие. Используйте get_channel_videos (1 единица) вместо search_within_channel (100 единиц), когда вам нужны просто последние загрузки.

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

Исправление API-ключа

Если вы ввели неверный API-ключ, удалите и переустановите:

claude mcp remove youtube

Затем переустановите, используя команду из шага 3.3 выше (используйте тот же scope, с которым вы устанавливали изначально).

MCP-сервер не отображается

Проверьте, установлен ли сервер:

claude mcp list

Если его нет в списке, выполните шаг 3, чтобы установить его.

Сервер не запускается

1. Проверьте, что ваш API-ключ действителен на Google Cloud Console

2. Проверьте, что YouTube Data API включен:

   • Перейдите в API Library

   • Там должно быть указано «Enabled».

3. Проверьте версию Node.js (требуется 18+):

   node --version

4. Убедитесь, что сервер собран — если dist/index.js отсутствует, снова выполните npm install

Ошибки подключения

1. Проверьте, что dist/index.js существует — если нет, выполните npm install

2. Убедитесь, что путь является абсолютным в вашей команде claude mcp add

3. Перезапустите Claude Code после любых изменений конфигурации

Превышена квота

Если вы видите ошибки «quotaExceeded»:

• Подождите до полуночи по тихоокеанскому времени (квота сбрасывается ежедневно)

• Используйте другой API-ключ

• Отдавайте предпочтение недорогим инструментам (get_video_metadata за 1 единицу) вместо поисковых инструментов (100 единиц)

Транскрипт недоступен

В некоторых видео транскрипты отключены. Инструмент get_transcript вернёт понятное сообщение об ошибке. Попробуйте:

• Другой код языка (например, lang: "es")

• Автоматически созданные субтитры могут быть доступны, даже если ручные отсутствуют

Ошибки таймаута

Увеличьте переменную окружения YOUTUBE_TIMEOUT для медленных соединений:

claude mcp add -s user youtube -e YOUTUBE_API_KEY=YOUR_KEY -e YOUTUBE_TIMEOUT=60000 -- node /path/to/dist/index.js

Просмотр текущей конфигурации

claude mcp list

Вклад в проект

Pull request'ы приветствуются! Пожалуйста, сохраняйте простоту и доступность для новичков.

Лицензия

MIT

Сделано для сообщества Claude Code