youtube-transcript-mcp

MCP-сервер, который даёт программному агенту возможность читать и искать по транскриптам видео YouTube. Без API-ключа, без учётной записи Google, без регистрации. Он получает субтитры через публичные конечные точки YouTube и добавляет одну небольшую вещь, которой нет в простом дампе транскрипта: сводки по главам.

Это начиналось как небольшой инструмент для личного использования. Я постоянно сталкивался с разговорами, содержащими ссылку на YouTube, и мне нужно было знать, что на самом деле говорится в видео, а повторная вставка транскриптов отнимала время. Он превратился в переиспользуемый сервер, чтобы всё, что работает на Model Context Protocol, могло просто спросить.

Что он делает

• get_transcript(video_url_or_id, languages=["en"], include_timestamps=False) получает полный транскрипт в виде обычного текста. Он принимает полный URL YouTube (watch?v=, youtu.be, /embed/, /shorts/, /live/) или просто 11-символьный идентификатор видео.

• get_video_metadata(video_url_or_id) возвращает название, имя канала, URL канала и миниатюру через oEmbed-конечную точку YouTube без аутентификации. Он намеренно не возвращает дату публикации или полное описание, потому что для них нужен официальный ключ Data API, а вся суть здесь в том, что он вам не нужен.

• search_transcript(video_url_or_id, query, languages=["en"]) находит сегменты, соответствующие ключевому слову или фразе, без учёта регистра, каждый с временной меткой [mm:ss], чтобы модель могла указать, где в видео было сказано что-то.

• summarize_chapters(video_url_or_id, gap_seconds=4.0, min_chunk_seconds=45.0, languages=["en"]) разбивает транскрипт на приблизительные временные блоки по естественным паузам и возвращает их, чтобы агент мог резюмировать раздел за разделом, а не глотать один гигантский кусок. Это эвристика, а не настоящие данные глав YouTube.

Все инструменты возвращают обычную строку, включая ошибки (например, "Error: captions are disabled for this video"). Никакие исключения не всплывают к вызывающему агенту, и никакие трассировки стека не утекают.

Related MCP server: youtube-mcp

Что он намеренно не делает

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

• Он не зависит от YouTube Data API. Вы не можете получить даты публикации или полные описания без него, и это сделано намеренно.

• Он не кэширует. Два вызова одного и того же видео каждый раз загружают его заново. Для реального использования инструмента это нормально. Добавьте кэширование, если когда-нибудь понадобится при больших объёмах.

Установка

Требуется Python 3.11+ и uv.

uv sync

Запустите его отдельно, чтобы убедиться, что он запускается:

uv run server.py

Он ожидает ввода MCP stdio, поэтому будет казаться, что он ничего не делает, пока не подключится клиент. Это нормально. Ctrl+C для выхода.

Регистрация в MCP-клиенте

Добавьте его в настройки MCP вашего клиента. Сервер вызывается через stdio, поэтому конфигурация представляет собой командную строку. В качестве примера используем Claude CLI:

claude mcp add youtube-transcript -- uv --directory /absolute/path/to/youtube-transcript-mcp run server.py

Или в JSON-конфигурации:

{
  "mcpServers": {
    "youtube-transcript": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/youtube-transcript-mcp", "run", "server.py"]
    }
  }
}

Заметки, добытые с трудом

• Работают только видео с субтитрами (автоматическими или ручными). Видео без субтитров возвращает понятную ошибку, и это осознанный выбор: пустой результат выглядит как тихий сбой, а ошибка называет причину.

• Список языков важен. languages=["en"] получает английскую дорожку, если она существует. Если канал загружает видео только на другом языке, передайте этот код.

• Закрепите mcp>=1.28.1, но оставайтесь ниже 2.0. В mcp 2.x переименован mcp.server.fastmcp, и импорт молча ломается при запуске сервера. Вам нужна версия, которая действительно загружается.

Лицензия

MIT. См. LICENSE.