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 Library

   • Нажмите Enable

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

   • Перейдите в Credentials

   • Нажмите Create Credentials > API key

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 (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 (строка, обязательный) — любой URL YouTube или ID видео

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

get_transcript

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

Параметры:

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

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

search_transcript

Выполняет поиск ключевого слова или фразы в стенограмме видео.

Параметры:

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

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

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

extract_chapters

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

Параметры:

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

get_clean_transcript

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

Параметры:

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

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

get_most_replayed

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

Параметры:

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

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

search_videos

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

Параметры:

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

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

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

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

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

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

get_video_metadata

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

Параметры:

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

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

get_channel_info

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

Параметры:

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

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

get_playlist_items

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

Параметры:

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

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

get_channel_videos

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

Параметры:

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

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

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

get_trending_videos

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

Параметры:

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

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

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

search_within_channel

Выполняет поиск видео в конкретном канале YouTube.

Параметры:

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

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

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

get_video_comments

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

Параметры:

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

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

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

calculate_engagement

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

Параметры:

• url (строка, обязательный) — 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

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

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

Лицензия

MIT

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