YouTube Knowledge MCP

A Model Context Protocol (MCP) server that gives AI assistants the ability to search, analyze, and extract knowledge from YouTube videos. Works with Claude Desktop, Claude Code, Claude.ai, Cursor and any MCP-compatible client.

Supports both local (stdio) and remote (Streamable HTTP) transports.

Возможности

Находите и читайте

• Ищите видео и каналы по ключевому слову

• Получайте видео из плейлиста или канала

• Метаданные видео, канала и плейлиста, главы и популярные комментарии

• Транскрипты с временными метками, нарезанные по временному диапазону или главе, и ограниченные по размеру, чтобы трёхчасовое видео не переполнило ваш контекст

• Ищите внутри транскрипта и получайте ссылки ?t=, открывающие видео в нужный момент

• Пакетные инструменты: транскрипты сразу для многих видео или дайджест целого плейлиста

Извлекайте для монтажа

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

• Аудиоклипы в форматах mp3, m4a, wav, flac или opus

• Захватывайте кадр в любой момент времени без скачивания файла

• Экспортируйте субтитры в форматах SRT, WebVTT или обычного текста для Premiere, Resolve или CapCut

• Скачивайте полностью с пресетами качества

Сохраняйте то, что узнали (локальный режим)

• Сохраняйте сводки и заметки о навыках в локальную библиотеку

• Читайте их обратно и ищите по всем ним с полнотекстовым ранжированием

• Тегируйте, меняйте теги и удаляйте

Создайте базу знаний для канала (локальный режим)

• Считывайте целый канал в доступный для поиска корпус фрагментов с временными метками на любом языке субтитров; процесс возобновляемый и безопасно прерываемый — повторный запуск продолжает с места остановки и подхватывает новые загрузки

• Спрашивайте, что автор говорил о чём угодно, по всем видео, и получайте сами моменты со ссылками, открывающими видео в нужном месте

• Измеряйте канал: сколько было читаемого, ритм публикаций, темп речи и фразы, повторяющиеся в разных видео

• Ведите письменный профиль рядом с корпусом, основанный на фрагментах, на которые можно ссылаться

Создан для стабильной работы

• WebVTT разбирается эталонной реализацией W3C, а не самодельным сопоставителем

• Типизированные, практичные ошибки — «нет субтитров на en, попробуйте: fr, es, de» вместо стены yt-dlp stderr

• Таймауты, повторные попытки с экспоненциальной задержкой и ограничение параллелизма для каждого вызова yt-dlp

• check_health диагностирует отсутствующие или устаревшие yt-dlp и ffmpeg

• Структурированный вывод для каждого инструмента, а также MCP-ресурсы, подсказки и дополнения

Related MCP server: YouTube Translate MCP

Предварительные требования

• Node.js 22+

• yt-dlp — требуется для каждого инструмента. brew install yt-dlp (macOS) или pip install -U yt-dlp

• ffmpeg — требуется для загрузки, извлечения клипов и захвата кадров. Всё остальное работает без него.

Запустите инструмент check_health, чтобы убедиться, что оба установлены и актуальны. Устаревший yt-dlp — самая частая причина необъяснимых сбоев, поскольку YouTube часто меняется; yt-dlp -U исправляет большинство из них.

Установка

Через npm (рекомендуется)

npm install -g youtube-knowledge-mcp

Через npx (без установки)

Настройте напрямую через npx (см. раздел «Конфигурация»).

Из исходного кода

git clone https://github.com/teobouancheau/youtube-knowledge-mcp.git
cd youtube-knowledge-mcp
npm install
npm run build

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

Локальный (stdio) -- Claude Desktop, Claude Code, Cursor

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

{
  "mcpServers": {
    "youtube-knowledge": {
      "command": "npx",
      "args": ["-y", "youtube-knowledge-mcp"]
    }
  }
}

При глобальной установке

npm install -g youtube-knowledge-mcp

{
  "mcpServers": {
    "youtube-knowledge": {
      "command": "youtube-knowledge-mcp"
    }
  }
}

Расположение файлов конфигурации

Перезапустите клиент после обновления конфигурации.

Удалённый (HTTP) -- Claude.ai, Claude Mobile, Custom Connectors

Сервер поддерживает транспорт Streamable HTTP для удалённого доступа через официальные коннекторы Claude.

Каждое удалённое развёртывание — это ваше собственное. По замыслу здесь нет общего экземпляра, на который можно навести коннектор: каждый вызов обращается к yt-dlp, поэтому один хост, обслуживающий чужой трафик, — это хост, который YouTube ограничивает по скорости для всех сразу. Кнопка ниже разворачивает этот репозиторий в вашем собственном аккаунте Render примерно за две минуты, без клонирования.

Самостоятельное развёртывание

npm run build
npm run start:http

Сервер слушает порт PORT (по умолчанию 3000). Чтобы изменить, задайте переменную окружения PORT.

Docker

docker build -t youtube-knowledge-mcp .

TOKEN=$(openssl rand -hex 32) && echo "MCP_AUTH_TOKEN=$TOKEN"
docker run -p 3000:10000 -e MCP_AUTH_TOKEN="$TOKEN" youtube-knowledge-mcp

Токен выводится, потому что больше его не напечатает ничто: сервер пишет в журнал, что требуется токен, но никогда не выводит его значение. Отправляйте его как Authorization: Bearer $TOKEN.

Образ устанавливает PORT=10000 и открывает его; публикуйте его на любом порту хоста. Сборка происходит внутри образа, поэтому локально npm run build не нужен.

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

Кнопка открывает поток Blueprint в Render для render.yaml в этом репозитории, который собирает Docker-образ, направляет проверку здоровья на /health и генерирует MCP_AUTH_TOKEN для вас. Ни форка, ни клонирования, ни заполнения настроек — сервис ваш, в вашем аккаунте.

1. Нажмите кнопку и подтвердите. Render соберёт образ и развернёт его.

2. Откройте вкладку Environment сервиса и скопируйте сгенерированный MCP_AUTH_TOKEN. HTTP-транспорт отклоняет любой запрос без него, поэтому утёкший URL не означает открытый сервер.

3. Добавьте https://<your-service>.onrender.com/mcp как пользовательский коннектор с заголовком Authorization: Bearer <token>.

После создания сервиса стоит сделать следующее: задайте MCP_ALLOWED_HOSTS равным имени хоста вашего сервиса (<your-service>.onrender.com). Его нельзя заполнить из Blueprint, потому что имени хоста не существует, пока не существует сервиса, и он отклоняет запросы, приходящие под любым другим именем.

Ваш экземпляр не следует за этим репозиторием. Blueprint задаёт autoDeployTrigger: off, потому что автодеплой запускал бы код, отправленный сюда, в вашем аккаунте и под вашим токеном, без предварительного ознакомления. Чтобы получить более новую версию, используйте Manual Deploy в сервисе.

Бесплатный план засыпает после бездействия, поэтому первый вызов после паузы ждёт холодного старта. Любой платный план это устраняет.

Подключение через Claude.ai

1. Перейдите в Settings > Connectors

2. Нажмите Add custom connector

3. Введите URL вашего сервера (например, https://your-app.onrender.com/mcp)

4. Добавьте заголовок Authorization: Bearer <token>, если вы задали MCP_AUTH_TOKEN

5. Нажмите Add

Инструменты MCP

33 инструмента. 14 инструментов только для чтения работают через оба транспорта; 19, которые обращаются к вашей файловой системе, регистрируются только в локальном (stdio) режиме, поэтому удалённое развёртывание не может получить доступ к диску хоста.

Каждый инструмент возвращает читаемый текст и типизированный структурированный вывод, а также сообщает об ошибках в виде практичного сообщения — [NO_CAPTIONS] No "en" captions are available for this video. Call get_transcript again with one of: fr, es, de.

Обнаружение — удалённый + локальный

Транскрипты — удалённый + локальный

format: "timestamped" добавляет к каждой строке префикс [MM:SS] — используйте это, когда нужно сослаться на момент или дать ссылку на него. maxChars вместе с offset читает длинный транскрипт частями, а не возвращает сразу 100 000+ токенов.

Извлечение для монтажа — только локально

Клипы нарезаются

Библиотека знаний — только локально

Мозги каналов — только локально

build_brain — единственный, кто обращается к сети. Остальные получают канал из того, что уже есть на диске, поэтому работают офлайн и ничего не стоят при вызове.

Мозг хранит один язык субтитров; передайте language, чтобы прочитать другой, и создайте отдельный мозг для каждого языка.

since и minDurationSeconds описывают мозг, а не только вызов, который их передал. Они применяются заново каждый раз, поэтому сужение одного отбрасывает фрагменты исключённых видео, а расширение снова их читает — именно поэтому build_brain помечен как разрушительный. То, соответствует ли видео критериям, определяется по уже записанным дате и длительности, так что изменение решения не требует запросов, пока нет новых данных для получения. Эти значения берутся из метаданных каждого видео, а не из предположений: плоский список канала вообще не содержит даты публикации.

build_brain также восстанавливает. Если файл фрагментов утерян или обрезан, видео, которые он больше не может учесть, будут прочитаны снова при следующем вызове, а не пропущены навсегда как уже обработанные.

Промпты

Многократно используемые рабочие процессы, которые ваш клиент может вызывать напрямую: summarize_video, extract_skill, compare_videos, research_topic, channel_deep_dive, clip_from_quote (найти фразу, затем вырезать клип вокруг неё), а также — только локально — review_library, create_brain (собрать корпус канала, затем составить из него профиль) и ask_creator (ответить на вопрос строго по мозгу, с цитатами).

Ресурсы

• youtube://transcript/{videoId} — расшифровка с временными метками, получается и кэшируется при первом чтении

• youtube://library/{videoId}/{summary|skill} — сохранённая заметка (только локально, перечисляемая)

• youtube://brain/{channelId}/{manifest|profile} — что покрывает мозг канала или профиль, созданный из него (только локально, перечисляемый)

Коды ошибок

Ошибки сообщаются внутри результата, чтобы модель могла их прочитать и восстановиться; каждая сопровождается кодом и следующим шагом.

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

Все необязательные.

Хранилище библиотеки

Содержимое хранится в ~/.youtube-knowledge/:

~/.youtube-knowledge/
├── transcripts/          # Cached timestamped transcripts
│   └── {video_id}.{lang}.json
├── library/              # Saved notes
│   └── {video_id}/
│       ├── metadata.json
│       ├── summary.md
│       └── skill.md
├── brains/               # Channel brains
│   └── {channel_id}/
│       ├── manifest.json # What the brain covers, and where a build stopped
│       ├── chunks.json   # The timestamped passages
│       └── profile.md    # The written account, if one was saved
├── downloads/            # Full downloads
├── clips/                # Extracted clips
├── frames/               # Captured stills
├── subtitles/            # Exported SRT / VTT / TXT
├── index.json            # Library index
└── search-index.json     # Full-text search index

Расшифровки кэшируются по умолчанию 30 дней; передайте refresh: true любому инструменту работы с расшифровками, чтобы обойти кэш, или установите YOUTUBE_MCP_TRANSCRIPT_TTL_MS.

Каждый инструмент, который записывает файлы, ограничивает вывод вашим домашним каталогом, а outputDir отклоняется, если указывает куда-либо ещё.

Примеры использования

Найти момент и процитировать его

"Find where this video talks about rate limiting and give me the timestamp:
 https://youtube.com/watch?v=..."

search_transcript возвращает каждое совпадение со ссылкой, открывающей видео на этой секунде, так что утверждение можно проверить, а не принимать на веру.

Найти момент и вырезать клип

"Find where she says 'the real bottleneck was the database' and cut me a
 30-second clip around it"

search_transcript находит момент, extract_clip вырезает его. Загружается только диапазон байтов, покрывающий клип.

Прочитать один раздел длинного видео

"Summarize just the 'Benchmarks' chapter of this 3-hour podcast"

get_chapters находит раздел, затем get_transcript с параметром chapter: "Benchmarks" читает только эту часть, а не всё целиком.

Дёшево обозреть плейлист

"What does this 40-video course cover, and which three videos should I watch?"

digest_playlist возвращает метаданные и главы для каждого видео за один вызов.

Подготовить материалы для монтажа

"Pull these four moments as separate clips and export the subtitles as SRT"

extract_clips вырезает все четыре за один вызов; export_subtitles записывает файл, который ваш редактор может импортировать.

Создать и запросить базу знаний

"Summarize this video and save it to my library tagged 'databases'"
"What have I saved about connection pooling?"

save_to_library сохраняет его; search_library ищет по всему сохранённому с полнотекстовым ранжированием.

Создать мозг для автора

"Build a brain for @Fireship, then tell me everything they've said about Rust"

build_brain читает канал во фрагменты с временными метками — прервите его и вызовите снова, чтобы продолжить. Затем ask_brain отвечает на основе того, что было действительно сказано, возвращая сами моменты, чтобы каждое утверждение можно было проверить по видео. Запустите build_brain снова через месяц, и он прочитает только новые загрузки.

Тестирование

npm test              # Run all tests
npm run test:watch    # Watch mode
npm run test:coverage # Coverage report, with thresholds enforced

Набор тестов покрывает чистую логику напрямую, запускает реальный сервер через MCP-клиент по транспорту в памяти, проверяет библиотеку на настоящей временной файловой системе и сохраняет снимок манифеста инструментов, чтобы любое изменение публичной поверхности отображалось в виде просматриваемого диффа.

Разработка

npm run dev        # Watch mode
npm run build      # Build for production
npm run rebuild    # Clean and rebuild
npm start          # Run server (stdio)
npm run start:http # Run server (HTTP)
npm run validate   # Typecheck + lint + format check + test

CI прогоняет те же проверки на Node 22 и 24 для каждого пуша и pull request, затем запускает собранный сервер как реальный MCP-клиент для проверки манифеста.

Вклад

Вклад приветствуется — см. CONTRIBUTING.md о структуре проекта, стандартах кодирования и о том, как добавить инструмент.

Безопасность

HTTP-транспорт не требует аутентификации, если вы не установите MCP_AUTH_TOKEN. См. SECURITY.md перед тем, как открывать его за пределами localhost, а также для сообщения об уязвимости.

Лицензия

Лицензия MIT — подробности см. в LICENSE.

Благодарности

• yt-dlp за извлечение с YouTube

• Anthropic за Model Context Protocol