YouTube MCP Server

Адаптированный YouTube MCP-сервер на основе оригинального репозитория claude-code-youtube-mcp. Эта версия поддерживает оба транспорта — STDIO и Streamable HTTP, поэтому её можно запускать локально для Claude Code или разворачивать удалённо для пользовательского коннектора Claude.ai.

Сервер предоставляет инструменты YouTube Data API v3 для поиска видео, метаданных, информации о каналах, плейлистов, комментариев, трендовых видео, аналитики вовлечённости, транскриптов, глав, очистки через SponsorBlock и тепловых карт повторных просмотров.

Адаптировано из: https://github.com/wynandw87/claude-code-youtube-mcp

Запуск локально

npm install
npm run build
npm run start:http

Эндпоинты:

GET  /health
POST /mcp

Related MCP server: YouTube MCP Server

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

YOUTUBE_API_KEY=your_key_here

Не коммитьте ваш API-ключ в GitHub. Храните его в локальном окружении, в .env или в переменных окружения платформы развёртывания.

Развёртывание на Railway

1. Разверните этот GitHub-репозиторий на Railway.

2. Добавьте переменную окружения YOUTUBE_API_KEY в Railway.

3. Установите команду запуска:

npm run start:http

4. Используйте публичный MCP-эндпоинт:

https://your-domain/mcp

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

Шаг 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.

Возможности

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

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

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 видео

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

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

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

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

Лицензия

MIT

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