yt-playlist-organizer-mcp

MCP-сервер для организации плейлистов YouTube через YouTube Data API v3.

Он делает ровно одну вещь и ничего больше: создаёт, перечисляет, обновляет и удаляет плейлисты и их элементы. Он не касается видео, каналов, субтитров, комментариев, подписок или любых других ресурсов YouTube Data API.

Создан с использованием официального @modelcontextprotocol/sdk и REST-эндпоинтов YouTube Data API v3 (без тяжёлой зависимости googleapis).

Инструменты

Всё, что делает этот сервер. Других инструментов нет.

Плейлисты (/playlists)

Элементы плейлистов (/playlistItems)

Плюс auth_status для проверки, какие учётные данные настроены.

Related MCP server: youtube-mcp

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

Этот сервер вызывает только эндпоинты /playlists и /playlistItems. Остальная часть YouTube Data API вне области действия.

Сервер считывает две переменные окружения:

См. .env.example.

• Чтения (..._list) работают только с ключом API (или токеном доступа).

• Записи (insert/update/delete) и mine=true требуют OAuth2-токен доступа с областями youtube, youtube.force-ssl или youtubepartner.

Получение учётных данных OAuth2

1. Создайте проект в Google Cloud Console.

2. Включите YouTube Data API v3.

3. Создайте идентификатор клиента OAuth2 (Desktop app) и скачайте JSON.

4. Обменяйте учётные данные на токен доступа (например, через google-auth-oauthlib на Python или локальный сервис OAuth-потока). Установите YOUTUBE_ACCESS_TOKEN=<token>.

5. (Необязательно) Создайте ключ API для более простого использования только для чтения.

Nix

Этот проект дружелюбен к NixOS. Предоставлены и flake, и shell.nix.

# Enter the dev shell (node + typescript toolchain)
nix develop

# or, non-flake:
nix-shell

Сборка

npm install        # install node deps (zod + MCP SDK)
npm run build      # emits dist/
npm run typecheck  # tsc --noEmit

Локальный запуск

# Reads only (API key):
YOUTUBE_API_KEY=... node dist/index.js

# Reads + writes/mine (OAuth access token):
YOUTUBE_ACCESS_TOKEN=... node dist/index.js

Подключение к opencode

Добавьте следующее в ~/.config/opencode/opencode.jsonc в раздел mcp:

"mcp": {
  "yt-playlist-organizer-mcp": {
    "type": "local",
    "command": ["node", "<path-to-repo>/dist/index.js"],
    "enabled": true,
    "environment": {
      "YOUTUBE_API_KEY": "{file:~/.secrets/yt-api-key}",
      "YOUTUBE_ACCESS_TOKEN": "{file:~/.secrets/yt-access-token}"
    }
  }
}

Замените <path-to-repo> на абсолютный путь, куда вы клонировали репозиторий, или установите его через npm, чтобы запускать по имени:

npm install -g .
# then use:  "command": ["yt-playlist-organizer-mcp"]

Чтобы запустить через Nix shell, используйте тот же ключ, но измените command:

"command": ["nix", "develop", "<path-to-repo>", "--command", "node", "dist/index.js"],

Примечания

• Стоимость квоты указана согласно официальной документации API и задокументирована для каждого инструмента.

• Значения part проверяются на соответствие допустимым наборам для каждого ресурса.

• playlists_list / playlistItems_list требуют ровно один параметр фильтра; в противном случае проверка входных данных отклоняет вызов.

• Инструменты обновления (playlists_update, playlistItems_update) сначала читают существующий ресурс и сохраняют все опущенные поля (например, description, privacyStatus, position, contentDetails), а не очищают их. Поэтому каждое обновление стоит дополнительного чтения из вашей квоты.

• startAt/endAt указываются в секундах и преобразуются в длительности ISO 8601 (PT1M30S) перед отправкой в API.

Разработка

npm install
npm test         # vitest unit tests
npm run typecheck
npm run build

Лицензия

MIT