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 на ваш настоящий API-ключ 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-mcp

Возможности

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

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

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

• Clean Transcript (get_clean_transcript) — транскрипт, в котором с помощью SponsorBlock удалены спонсорские вставки, интро, аутро и лишние слова

• Extract Chapters (extract_chapters) — извлечение временных меток глав из описания видео

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

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

• Search Within Channel (search_within_channel) — поиск видео у конкретного автора

• Get Trending Videos (get_trending_videos) — текущие трендовые видео по региону и категории

• Get Channel Videos (get_channel_videos) — недавние загрузки канала, отсортированные по дате или количеству просмотров

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

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

• Channel Info (get_channel_info) — количество подписчиков, количество видео, описание, страна

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

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

• Calculate Engagement (calculate_engagement) — коэффициент лайков, коэффициент комментариев и коэффициент вовлечённости на основе публичной статистики

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

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

Утилиты

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

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

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

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

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

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

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

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

• "Получи комментарии к этому видео и оцени их тональность"

• "Покажи главы этого урока"

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

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

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

parse_youtube_url

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

Параметры:

• url (string, обязательный) — любой URL YouTube или ID видео

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

get_transcript

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

Параметры:

• url (string, обязательный) — URL видео на YouTube или ID видео

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

search_transcript

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

Параметры:

• url (string, обязательный) — URL видео на YouTube или ID видео

• query (string, обязательный) — ключевое слово или фраза для поиска

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

extract_chapters

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

Параметры:

• url (string, обязательный) — URL видео на YouTube или ID видео

get_clean_transcript

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

Параметры:

• url (string, обязательный) — URL видео на YouTube или ID видео

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

get_most_replayed

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

Параметры:

• url (string, обязательный) — URL видео на YouTube или ID видео

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

search_videos

Выполняет поиск по YouTube с полной поддержкой фильтров.

Параметры:

• query (string, обязательный) — поисковый запрос

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

• order (string, необязательный) — "relevance", "date", "viewCount", "rating" (по умолчанию: "relevance")

• duration (string, необязательный) — "short" (<4 мин), "medium" (4-20 мин), "long" (>20 мин)

• upload_date (string, необязательный) — "hour", "day", "week", "month", "year"

• type (string, необязательный) — "video", "channel", "playlist" (по умолчанию: "video")

get_video_metadata

Возвращает подробные метаданные видео с YouTube.

Параметры:

• url (string, обязательный) — URL видео на YouTube или ID видео

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

get_channel_info

Возвращает информацию о канале YouTube.

Параметры:

• url (string, обязательный) — URL канала YouTube, @handle или ID канала

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

get_playlist_items

Возвращает все видео в плейлисте YouTube.

Параметры:

• url (string, обязательный) — URL плейлиста YouTube или ID плейлиста

• max_results (number, необязательный) — количество элементов, от 1 до 50 (по умолчанию: 25)

get_channel_videos

Возвращает недавние видео с канала YouTube.

Параметры:

• url (string, обязательный) — URL канала YouTube, @handle или ID канала

• max_results (number, необязательный) — количество видео, от 1 до 50 (по умолчанию: 25)

• order (string, необязательный) — "date", "viewCount" (по умолчанию: "date")

get_trending_videos

Возвращает текущие трендовые/популярные видео YouTube.

Параметры:

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

• category_id (string, необязательный) — ID категории YouTube (например, "10" для музыки, "20" для игр, "28" для науки и технологий)

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

search_within_channel

Ищет видео в конкретном канале YouTube.

Параметры:

• url (string, обязательный) — URL канала YouTube, @handle или ID канала

• query (string, обязательный) — поисковый запрос

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

get_video_comments

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

Параметры:

• url (string, обязательный) — URL видео на YouTube или ID видео

• max_results (number, необязательный) — количество комментариев, от 1 до 100 (по умолчанию: 20)

• order (string, необязательный) — "relevance", "time" (по умолчанию: "relevance")

calculate_engagement

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

Параметры:

• url (string, обязательный) — 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 выше (используйте ту же область видимости, что и при первоначальной установке).

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