ytmusic-mcp

Сервер MCP, который оборачивает ytmusicapi, чтобы Claude (или любой MCP-клиент) мог искать в YouTube Music, управлять вашими плейлистами и читать историю прослушивания.

Инструменты

Не включено (v1): Рекомендации на основе BPM. YouTube Music не предоставляет данные о темпе, поэтому для этого потребуется второй источник данных (например, API анализа аудио) — это задача на будущее, не входящая в текущую сборку.

Related MCP server: mcp-server-youtube

Настройка

1. Установка зависимостей

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

2. Аутентификация

Официального API YouTube Music нет, поэтому ytmusicapi аутентифицируется, повторно используя заголовки из вашего сеанса браузера, в котором вы вошли.

1. Откройте music.youtube.com в Firefox (рекомендуется — копирование сырых заголовков в нём надёжнее, чем в Chrome) будучи авторизованным.

2. Откройте DevTools (Cmd+Option+I / F12) → вкладка Network → фильтр по browse.

3. Нажмите на плейлист или перезагрузите страницу, чтобы вызвать POST-запрос browse.

4. Нажмите на этот запрос → вкладка Headers → включите Raw headers → выделите и скопируйте весь блок.

5. Вставьте его в новый файл с именем raw_headers.txt в корне проекта и сохраните.

6. Запустите:

python scripts/setup_auth_from_file.py

Это создаст headers_auth.json и удалит raw_headers.txt.

Альтернативно, python scripts/setup_auth.py делает то же самое через интерактивный запрос в терминале вместо файла, если вы предпочитаете вставлять напрямую.

headers_auth.json эквивалентен вашему авторизованному сеансу — никогда не коммитьте и не делитесь им. Он уже добавлен в .gitignore.

Проверьте, что аутентификация работает, прежде чем продолжить:

python scripts/test_search.py

Эти заголовки периодически истекают/обновляются. Если инструменты начинают выдавать ошибку аутентификации, повторите этот шаг.

3. Добавление в Claude Code

claude mcp add ytmusic -s user \
  -e YTMUSIC_AUTH_PATH="$(pwd)/headers_auth.json" \
  -- "$(pwd)/.venv/bin/python" "$(pwd)/server.py"

-s user делает его доступным в любом сеансе Claude Code, а не только в этой директории. Используйте абсолютные пути для интерпретатора python, server.py и YTMUSIC_AUTH_PATH, так как сервер может быть запущен из любой рабочей директории.

Для других MCP-клиентов (Claude Desktop и т.д.) укажите им ту же команду и переменную окружения, используя соответствующий формат конфигурации.

Обработка ошибок

Вызовы инструментов преобразуют распространённые сбои в понятные сообщения вместо сырых трассировок:

• Отсутствующая/просроченная/некорректная аутентификация → сообщает вам перезапустить scripts/setup_auth_from_file.py.

• Ограничение частоты запросов (HTTP 429) → сообщает подождать и повторить.

• Контент с ограниченным доступом → сообщается как недоступный, а не вызывает сбой.

• Сетевые ошибки → сообщаются напрямую.

Лицензия

MIT — см. LICENSE.