youtube-mcp-server

Удалённый MCP-сервер, который предоставляет YouTube Data API v3 в виде инструментов через Streamable HTTP, так что его можно добавить в claude.ai как пользовательский коннектор.

Никаких зависимостей. Никакого этапа сборки. node src/server.js — это всё.

Инструменты

Транскрипции намеренно отсутствуют. captions.download требует OAuth и прав на редактирование видео, поэтому API-ключ может получать субтитры только для видео, которыми вы владеете. По многочисленным сообщениям, неофициальные библиотеки для скрейпинга блокируются при обращении с облачных IP-диапазонов — а именно там работает этот сервер.

Related MCP server: mcp-server-youtube

Квота

Проект получает 10 000 единиц в день в общем пуле, а search.list находится в отдельном пуле с лимитом 100 вызовов в день. Это определило дизайн инструментов: youtube_channel_videos использует channels.list → playlistItems.list → videos.list вместо search.list?channelId=, поэтому просмотр канала стоит 3 единицы общего пула вместо одного из всего лишь сотни ежедневных поисков.

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

cp .env.example .env        # add your YOUTUBE_API_KEY
export $(grep -v '^#' .env | xargs)
npm start

curl localhost:3000/health

curl -s localhost:3000/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | head -c 400

Тест

npm test

Запускает полное рукопожатие MCP, оба транспортных режима, все пять инструментов и сценарии ошибок против заглушки YouTube API. Не требуется ни API-ключ, ни сеть.

Деплой на Railway

1. Отправьте этот репозиторий на GitHub.

2. Railway → New Project → Deploy from GitHub repo → выберите его.

3. Variables → добавьте YOUTUBE_API_KEY.

4. Settings → Networking → Generate Domain.

5. Проверьте, что https://<your-domain>/health возвращает "apiKeyConfigured": true.

Railway сам задаёт PORT; сервер привязывается к 0.0.0.0 и считывает его.

Подключение к claude.ai

Customize → Connectors → Add custom connector → https://<your-domain>/mcp

Поля OAuth не нужны — по умолчанию сервер работает без аутентификации. Чтобы закрыть доступ, задайте MCP_AUTH_TOKEN и укажите Bearer <token> в заголовках запроса коннектора в поле authorization.

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

Заметки по дизайну

Без состояния. Каждый POST самодостаточен — ни Mcp-Session-Id, ни карты сессий, — поэтому перезапуск или вторая реплика никогда не приводят к ошибке "No valid session ID provided".

Согласование содержимого соответствует эталонному SDK: SSE-кадр, когда клиент отправляет Accept: text/event-stream, и обычное JSON-тело в остальных случаях.

GET и DELETE на /mcp возвращают 405 — именно этого ожидает спецификация Streamable HTTP от сервера без инициируемого сервером потока и без сессии, которую нужно закрывать.

Никакой проверки заголовка Origin и ни какой защиты от DNS-rebinding. Эти меры защиты предназначены для MCP-серверов, привязанных к localhost; если оставить их включёнными для публичного развёртывания, они будут отклонять собственные запросы Anthropic, что является частой причиной тайм-аутов initialize.

Сбои инструментов возвращаются как содержимое с isError: true, а не как JSON-RPC ошибки, поэтому Claude видит, что пошло не так, и может скорректировать действия, вмест того чтобы вызов завершался ошибкой на транспорном уровне.

Результаты обрезаются до 120k симоволов, что меньше огранчения claude.ai на результат инструмента — ~150k.