YouTube Transcript & Search MCP Server

🎬 Зачем

Каждый, кто работает с агентом, хотя бы раз сталкивался с таким диалогом.

You:   Summarize this. https://www.youtube.com/watch?v=kCc8FmEb1nY
Agent: I'm not able to watch videos. If you paste the transcript here, I'll gladly help!

Транскрипт — это именно то, что агент не может получить самостоятельно. С подключённым этим сервером тот же запрос просто решается.

You:   Summarize this. https://www.youtube.com/watch?v=kCc8FmEb1nY
Agent: → get_transcript(video="kCc8FmEb1nY", video_metadata=true)      1 credit

       That's "Let's build GPT: from scratch, in code, spelled out" by Andrej
       Karpathy, 1:56:20. He starts from an empty file and a bigram model,
       derives self-attention step by step, and ends with a working GPT that...

Работа редко заканчивается одним видео. Вот честное сравнение трёх способов передать данные YouTube агенту.

Related MCP server: VidLens

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

1. Получите API-ключ. Зарегистрируйтесь на transcriptout.com и создайте ключ в панели управления. Новые аккаунты получают 100 бесплатных кредитов, автовпомен. Ключи начинаются с sk_ и показываются только один раз.

2. Направьте ваш клиент на сервер. Он работает по потоковому HTTP (streamable HTTP) и аутентифицируется одним Bearer-заголовком.

{
  "mcpServers": {
    "transcriptout": {
      "url": "https://api.transcriptout.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Кнопки в один клик для Cursor и VS Code — вверху страницы. Точные фрагменты для остальных клиентов — в разделе Установка в вашем клиенте.

3. Вставьте ссылку.

Summarize this talk and pull the three strongest quotes.
https://www.youtube.com/watch?v=dQw4w9WgXcQ

Агент сам выберет get_transcript, прочитает текст с таймкодами и ответит на его основе. Каждый ответ содержит заголовок X-Credits-Remaining, так что баланс виден на всём протяжении сессии.

🧰 14 инструментов

Все 14 инструментов подключаются автоматически. Большинство вызовов стоят 1 кредит. Кредиты возвращаются автоматически, когда вызов падает до достигнутого YouTube (ошибки валидации, rate limits, отсутствие мощностей у нас), — so вы платите за ответы, а не за сбои. Точное «в этом видео нет субтитров» — ответ, и она тарифицируется как ответ.

1. get_transcript · 1 кредит

Получает транскрипт любого видео YouTube. format=text (по умолчанию) возвращает простой читаемый текст — это самый дешёвый вариант для рассуждений модели, — а format=json возвращает тайм-кодами сегменты.

Если segment не задан, записи автоматических дорожек нарезаются на сегменты по ~180 символов, а ручные дорожки возвращаются так, как автор их разбил. Передавайте segment, когда нужно получить единый размер независимо от того, какая дорожка отвечает.

Пример вывода (format=json):

{
  "video_id": "dQw4w9WgXcQ",
  "language": "en",
  "kind": "manual",
  "transcript": [
    { "text": "Never gonna give you up", "start": 18.0, "duration": 4.12 },
    { "text": "Never gonna let you down", "start": 22.12, "duration": 3.85 }
  ]
}

srt и vtt возвращаются как полные тела файлов with колба своими субтитрами, готовые к записи на диск агентом. srv3 — это исходный XML и не сочетается с segment.

2. get_video_info · 1 кредит

Метаданные одного видео (название, канал,длительность, просмотры, превью) плюс список доступных языков — БЕЗ скачивания субтитров.

Гигиена кредита. Если один транскрипт и так понадобится, вызовите get_transcript с video_metadata=true: за один кредит получите оба данных, сколько бы ни было вызовов.

3. search_youtube · 1 кредит/страница

Ищет на YouTube видео или каналы. Пагинация через next_page_token. has_more сообщает, есть ли ещё страницы.

4. list_channel_videos · 1 кредит/страница

Список видео с вкладки «Видео» канала, новые сверху. Принимает @handle, название канала, UC... id канала или URL канала.

ids_only=true — дешёвый способ передать ID в submit_transcripts_job.

4. search_channel_videos · 1 кредит/страница

Ищет внутри одного канала с использованием нативного поиска YouTube по релевантности. Результат, в заголовке которого нет слова из запроса, — норма. Результаты сортируются по релевантности, а не по substring.

6. latest_channel_videos · 1 кредит

Последние ~15 видео канала из его RSS-ленты. Быстрейший и самый дешёвый способ узнать, что канал недавно публиковался.

7. list_playlist_videos · 1 кредит/страница

Все видео плейлиста в порядке плейлиста. Принимает PL... ID плейлиста или URL с list=.

8. search_playlist_videos · 1 credit

Ищет видео внутри плейлиста по подстроке названия (без учёта регистра). YouTube не даёт соответствующий поиск по плейлисту, поэтому сканируются до 500 пунктов плейлиста. truncated=true означает, что за пределами просканированного окна могут остаться ещё совпадения.

9. submit_transcripts_job · 1 кредит за видео

Поставьте в очередь расшифровки для МНОГИХ видео сразу (до 4 000) и получите job_id немедленно. Работа продолжается в фоне со скоростью, которую допускает ваш rate limit. Используйте этот метод вместо вызова get_transcript в цикле, когда видео больше двух-трёх.

Требуется пользовательский ключ (sk_...). Кредиты списываются при отправке и возвращаются за каждое видео, которое не удалось доставить по нашей вине.

10. get_transcripts_job · бесплатно

Ход выполнения пакетного задания: статус (queued/running/done/cancelled), сколько видео готово, завершилось ошибкой и ожидает. Проверять уже оплаченное задание ничего не стоит.

11. get_transcripts_results · бесплатно

Готовые расшифровки из пакетного задания, в порядке отправки, постранично через next_page_token (limit 1–500, по умолчанию 100). Результаты появляются по мере получения, поэтому их можно читать до завершения задания. Каждая запись — это ровно то, что возвращает get_transcript для этого видео, плюс его статус.

12. get_transcripts_result · бесплатно

Результат одного видео из пакетного задания по его video_id, без пролистывания всего набора результатов. Код 404 означает, что задание не существует или видео ещё не готово, поэтому прежде чем делать выводы, проверьте get_transcripts_job.

13. cancel_transcripts_job · бесплатно

Отменить пакетное задание. Кредиты возвращаются ТОЛЬКО за видео, обработка которых ещё не началась. Всё уже полученное остаётся в результатах и остаётся оплаченным.

14. get_credits · бесплатно

Текущий остаток кредитов ключа, без параметров. Остаток также передаётся в заголовке X-Credits-Remaining каждого ответа, но заголовки не видны модели, поэтому для числа, о котором спрашивает пользователь, нужен инструмент. Это удобно и прямо перед большим пакетным запуском, поскольку при отправке пакет списывает 1 кредит за видео.

🔌 Установка в вашем клиенте

Сервер находится удалённо, поэтому каждая установка ниже — это запись конфигурации и не более. Во всех случаях нужны одни и те же два значения: URL и заголовок Bearer из раздела Быстрый старт.

Стоит сделать один раз — постоянное правило для вашего клиента

Если добавить это в правила/инструкции клиента, вставки ссылки на YouTube достаточно, и слово «transcript» никогда не придётся вводить:

Whenever a YouTube link or video ID appears in my message, call the
transcriptout get_transcript tool first and answer from the transcript,
whether I asked for a summary, a quote, a translation or a question.

Установка в один клик:

После установки откройте настройки сервера и добавьте заголовок Authorization со своим ключом.

Ручная настройка (~/.cursor/mcp.json):

{
  "mcpServers": {
    "transcriptout": {
      "url": "https://api.transcriptout.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

claude mcp add --transport http transcriptout https://api.transcriptout.com/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Пользовательские коннекторы Claude поддерживают аутентификацию удалённых серверов через OAuth, которого TranscriptOut пока не предлагает (только API-ключи). На десктопе используйте Claude Code (см. выше), который поддерживает заголовки API-ключей. Поддержка OAuth — в планах. Следите за changelog.

Или добавьте в пользовательские настройки VS Code (settings.json):

"mcp.servers": {
  "transcriptout": {
    "type": "http",
    "url": "https://api.transcriptout.com/mcp",
    "headers": {
      "Authorization": "Bearer YOUR_API_KEY"
    }
  }
}

1. Создайте нового агента

2. В разделе «Actions» или «Tools» добавьте новый MCP Server

3. URL: https://api.transcriptout.com/mcp

4. Тип аутентификации: API Key

5. Вставьте ваш API-ключ из панели управления

Добавьте в ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "transcriptout": {
      "serverUrl": "https://api.transcriptout.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "transcriptout": {
      "url": "https://api.transcriptout.com/mcp",
      "type": "streamableHttp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

В settings.json Zed:

{
  "context_servers": {
    "transcriptout": {
      "source": "remote",
      "url": "https://api.transcriptout.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "transcriptout": {
      "type": "streamable-http",
      "url": "https://api.transcriptout.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

amp mcp add transcriptout https://api.transcriptout.com/mcp --header "Authorization: Bearer YOUR_API_KEY"

В settings.json в разделе augment.advanced:

"augment.advanced": {
  "mcpServers": [
    {
      "name": "transcriptout",
      "url": "https://api.transcriptout.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  ]
}

В .kilocode/mcp.json:

{
  "mcpServers": {
    "transcriptout": {
      "type": "streamable-http",
      "url": "https://api.transcriptout.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

В Settings → Tools → AI Assistant → MCP:

{
  "mcpServers": {
    "transcriptout": {
      "url": "https://api.transcriptout.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

В ~/.gemini/settings.json:

{
  "mcpServers": {
    "transcriptout": {
      "httpUrl": "https://api.transcriptout.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

В ~/.qwen/settings.json:

{
  "mcpServers": {
    "transcriptout": {
      "httpUrl": "https://api.transcriptout.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "transcriptout": {
      "serverUrl": "https://api.transcriptout.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "transcriptout": {
      "url": "https://api.transcriptout.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

В mcp.json:

{
  "mcpServers": {
    "transcriptout": {
      "url": "https://api.transcriptout.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

В Settings → AI → MCP:

{
  "transcriptout": {
    "url": "https://api.transcriptout.com/mcp",
    "headers": {
      "Authorization": "Bearer YOUR_API_KEY"
    }
  }
}

В Settings → Connectors → Advanced:

{
  "url": "https://api.transcriptout.com/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_API_KEY"
  }
}

🧩 Установка как плагина для агента

Корень этого репозитория — пакет, соответствующий спецификации Agent Plugins 1.0.0, переносимому формату, который поддерживается в ChatGPT, Codex, Cursor, GitHub Copilot, Kiro и VS Code. Одна установка даёт вам MCP-сервер и встроенный навык youtube, который учит агента, когда использовать каждый инструмент и как не тратить кредиты.

plugin.json                # manifest
mcp.json                   # hosted MCP server, streamable-http
skills/youtube/SKILL.md    # when + how to use the 14 tools

VS Code. Палитра команд → Chat: Install Plugin From Source, затем вставьте:

https://github.com/artemchuikin/youtube-mcp

Или зарегистрируйте локальную копию в settings.json:

"chat.pluginLocations": { "/absolute/path/to/youtube-mcp": true }

Cursor. Customize в боковой панели → найдите плагин → Install. Для локальной копии:

git clone https://github.com/artemchuikin/youtube-mcp ~/.cursor/plugins/local/transcriptout

Затем Developer: Reload Window.

ChatGPT, Codex, GitHub Copilot, Kiro и любые другие клиенты. Направьте механизм плагинов вашего клиента на этот репозиторий или на локальную копию. Agent Plugins 1.0.0 стандартизирует формат пакета, а не установку, поэтому каждый клиент управляет своей установкой.

В этом пакете нет учётных данных — Agent Plugins 1.0.0 запрещает встраивать секреты. Сервер аутентифицируется с помощью API-ключа, который вы добавляете в настройки MCP вашего клиента (см. Ключи и безопасность). Проверьте пакет самостоятельно:

curl -sO https://agent-plugins.org/schemas/1.0.0/plugin.schema.json
curl -sO https://agent-plugins.org/schemas/1.0.0/mcp.schema.json
npx ajv-cli@5 validate --spec=draft2020 -s plugin.schema.json -d plugin.json
npx ajv-cli@5 validate --spec=draft2020 -s mcp.schema.json    -d mcp.json

🔑 Ключи и безопасность

• Ключ показывается один раз при создании. Храните его в переменной окружения, а не в системе контроля версий.

• Утёкший ключ становится мёртвым в тот момент, когда вы отозвали его в панели dashboard. Аккаунт содержит до 20 ключей, поэтому дайте каждой машине свой ключ.

• Предпочитаете оставаться в чате? Агент с установленным сопутствующим youtube-skills может открыть аккаунт и выпустить ключ за вас, по email и 6-значному коду, без браузера.

• OAuth-потока пока нет, поэтому клиенты, чьи коннекторы не могут отправлять кастомный заголовок (Claude Desktop и Claude Web), должны пока работать через Claude Code.

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

Размещённый эндпоинт не требует установки, но клиентам с только stdin, песочницам и контейнерным платформам иногда нужен собственный процесс. В репозитории он есть: server.js — это полнофункциональный локальный MCP-сервер (официальный SDK, stdio transport), чьи 14 инструментов делают по одному HTTPS-запросу к REST API TranscriptOut — та же схема, что у любого SaaS-бэкенда MCP-сервера.

# as a container
docker build -t transcriptout-mcp https://github.com/artemchuikin/youtube-mcp.git
docker run -i -e TRANSCRIPTOUT_API_KEY=sk_your_key transcriptout-mcp

# or straight from a checkout (Node 20+)
npm install && TRANSCRIPTOUT_API_KEY=sk_your_key node server.js

Без ключа он по-прежнему подключается и показывает все инструменты; вызовы инструментов отвечают понятной ошибкой 401 с указанием, где получить ключ. Определения инструментов поставляются в tools.json и при запуске при наличии сети обновляются из актуального каталога, так что локальный список никогда не устаревает.

🍳 Рецепты

Каждый промпт ниже можно вставить как есть.

Быстрый рецепт для массовой задачи. «Архивировать целый канал» — это четыре вызова инструмента, а не скрипт:

1. list_channel_videos с ids_only=true: до 500 ID видео на страницу

2. submit_transcripts_job с этими ID (до 4 000; дубликаты отбрасываются до списания, idempotency_key делает повторный запрос бесплатным)

3. get_transcripts_job до тех пор, пока status не станет done. Задача сама подстраивает темп под ваш лимит запросов

4. get_transcripts_results постранично — результат можно читать, пока задача ещё работает

Если сервис не смог выдать какое-то видео, за него возвращаются деньги, поэтому итоговый счёт соответствует составу архива.

💳 Тарифы и лимиты

• Подписка выбирается слайдером от 1 000 до 100 000 кредитов в месяц с шагом в 1 000, и цена за 1 000 кредитов снижается с ростом объёма (10 000/мес стоят $27.49, а не $44.90). Годовая скидка увеличивается с ростом объёма — примерно от ~16% до ~35%.

• 1 кредит = 1 обслуженный запрос. Запросы, которые завершились ошибкой до обращения к YouTube (валидация, лимит запросов, наши мощности), автоматически возвращаются. Текущий баланс кредитов передаётся в заголовке X-Credits-Remaining.

• можно купить разовые пакеты кредитов без срока действия в дополнение к активной подписке.

• Смотреть тарифы · Управление оплатой

🧯 Если запрос завершился с ошибкой

• Убедитесь, что ваш API-ключ начинается с sk_

• Проверьте, не попали ли лишние пробелы при копировании

• Убедитесь, что ключ активен в вашей панели управления

• Отозванные ключи перестают работать сразу. Выдайте новый ключ в панели управления

• Проверьте баланс в панели управления

• Оформите подписку или купите пакет кредитов на transcriptout.com/billing

• 404: у видео нет субтитров с запрошенном языке/дорожке или ID указан неверно. Это окончательный и однозначный ответ, повторные попытки ничего не изменят.

• 410: видео было удалено.

• 451: контент с возрастным ограничением или доступный только по подписке.

• Следуйте заголовку Retry-After. В обоих случаях кредиты возвращаются автоматически

• Для массовой работы используйте submit_transcripts_job: он сам подстраивается под ваш лимит запросов, а не спотником в него

Тело любой ошибки — это {"ok": false, "code": "...", "detail": "...", "request_id": "req_..."}. Ориентируйтесь на машиночитаемое code, а не на текст для человека. При обращениях в поддержку показывайте request_id.

🌐 Предпочитаете обычный REST?

Создаёте приложение, а не агента? Этот же бэкенд поставляется как JSON REST API, с теми же пятью форматами транскриптов и загрузкой исходного файла (download=true).

Базовый URL: https://api.transcriptout.com/v1

🔗 Ссылки

• 🌐 Сайт: transcriptout.com

• 📚 Документация: transcriptout.com/docs

• 🧰 Навыки для агентов (тот же бэкенд, MCP не требуется): github.com/artemchuikin/youtube-skills

• 💬 Контакты: support@transcriptout.com

📇 Реестр MCP

Этот сервер опубликован в официальном Реестре Model Context Protocol под именем:

com.transcriptout/youtube-transcript-and-youtube-search

TranscriptOut — независимый сервис; он не аффилирован с YouTube или Google LLC, не одобрен и не спонсируется ими. "YouTube" является товарным знаком Google LLC.