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) — популярные комментарии с количеством лайков и ответов

Утилиты

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

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

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

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

• «Получи транскрипт этого видео YouTube и сделай саммари»

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

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

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

• «Получи комментарии к этому видео и резюмируй тональность»

• «Покажи главы для этого урока»

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

• «Что сейчас популярно на YouTube в разделе игр?»

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

parse_youtube_url

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

Параметры:

• url (string, required) — любая ссылка YouTube или ID видео

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

get_transcript

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

Параметры:

• url (string, required) — ссылка на видео YouTube или ID видео

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

search_transcript

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

Параметры:

• url (string, required) — ссылка на видео YouTube или ID видео

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

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

extract_chapters

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

Параметры:

• url (string, required) — ссылка на видео YouTube или ID видео

get_clean_transcript

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

Параметры:

• url (string, required) — ссылка на видео YouTube или ID видео

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

get_most_replayed

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

Параметры:

• url (string, required) — ссылка на видео 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) — ссылка на видео YouTube или ID видео

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

get_channel_info

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

Параметры:

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

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

get_playlist_items

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

Параметры:

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

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

get_channel_videos

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

Параметры:

• url (string, required) — ссылка на канал 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) — ссылка на канал YouTube, @handle или ID канала

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

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

get_video_comments

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

Параметры:

• url (string, required) — ссылка на видео YouTube или ID видео

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

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

calculate_engagement

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

Параметры:

• url (string, required) — ссылка на видео 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

   • Там должно быть указано «Включено»

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

Участие в разработке

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

Лицензия

MIT

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