vdl-mcp

vdl-mcp подключает AI-ассистента к вашему собственному серверу vdl через Model Context Protocol. Настоящая сила — в синергии с Whisper:

Скачивание → транскрипция → ассистент понимает содержимое.

Так что вы можете говорить что-то вроде:

• "Скачай это видео с YouTube и сделай краткое содержание."

• "Захвати тот кулинарный клип и выпиши рецепт в виде списка."

• "Что было сказано о X в этом интервью?"

• "Скачай аудио этой лекции и дай мне ключевые моменты."

Как это работает

Это небольшой stdio MCP-сервер, который общается с REST API vdl и аутентифицируется с помощью вашего существующего API-токена. Ничего не запускается внутри самого vdl.

Группы инструментов переключаются с безопасными настройками по умолчанию:

Отключенная группа невидима для ассистента.

Related MCP server: popcorn

Требования

• Запущенный экземпляр vdl.

• MCP-токен: в vdl откройте вкладку MCP → создайте токен и скопируйте его. Этот токен ограничен — он может выполнять только те действия MCP, которые вы там разрешили (инструменты записи/удаления учитывают переключатели и режим только для чтения, всё остальное отклоняется на стороне сервера), поэтому он безопаснее, чем общий API-токен.

Установка

С помощью pipx (помещает vdl-mcp в ваш PATH):

pipx install git+https://github.com/sphings79/vdl-mcp

или с помощью uv:

uv tool install git+https://github.com/sphings79/vdl-mcp

Подключение к Claude Desktop

Добавьте это в конфигурацию Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "vdl": {
      "command": "vdl-mcp",
      "env": {
        "VDL_URL": "http://localhost:8000",
        "VDL_TOKEN": "your-api-token"
      }
    }
  }
}

Перезапустите Claude Desktop — появятся инструменты vdl. (Любой MCP-совместимый клиент работает так же; просто запустите команду vdl-mcp через stdio.)

Запуск с Docker

Предпочитаете контейнер? Предварительно собранный образ опубликован в GHCR — используйте его как команду:

{
  "mcpServers": {
    "vdl": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
               "-e", "VDL_URL", "-e", "VDL_TOKEN",
               "ghcr.io/sphings79/vdl-mcp:latest"],
      "env": {
        "VDL_URL": "http://host.docker.internal:8000",
        "VDL_TOKEN": "your-api-token"
      }
    }
  }
}

Обратите внимание на -i (держать stdin открытым для stdio) и, когда vdl работает на том же хосте, host.docker.internal, чтобы контейнер мог до него добраться.

Нет веб-интерфейса — по замыслу

vdl-mcp — это stdio-процесс, запускаемый локально вашим MCP-клиентом. Он не открывает сетевой порт, поэтому у него нет страницы входа и нет fail2ban — нечего защищать извне. Его модель безопасности: храните API-токен в тайне, оставьте разрушительные инструменты выключенными (по умолчанию) и, при желании, установите белый список доменов. Аутентификация и защита от перебора находятся в самом vdl. (Если вам когда-нибудь понадобится удаленный HTTP-сервер для нескольких клиентов, это другой транспорт — создайте issue.)

Инструменты

• resolve(url) — проанализировать ссылку, перечислить элементы и доступные качества (без скачивания).

• download(url, audio=False, section="", wait=True) — скачать лучшее качество (или MP3); section типа 0:30-1:00 обрезает; wait возвращает имя готового файла name.

• transcribe(name, language="") — транскрипция Whisper → возвращает текст (требуется установленная модель Whisper в vdl).

• get_transcript(name) — вернуть текст существующей транскрипции.

• list_files(query, service, label, limit) — просмотреть ваши загрузки.

• job_status(job_id) — проверить задачу скачивания.

• (выключено по умолчанию) delete_file, bulk, get_settings.

Конфигурация (переменные окружения)

Каждый инструмент помечен в его описании — [read], [writes] или [deletes] — чтобы и вы, и ассистент могли сразу видеть его риск.

Управляйте им также из веб-интерфейса vdl: в vdl перейдите в Настройки → вкладка MCP, чтобы переключать каждый инструмент (с главным выключателем только для чтения и чипами риска). vdl-mcp загружает эту конфигурацию при запуске, поэтому переменные окружения не нужны — перезапустите vdl-mcp после изменений. Приоритет для того, показывается ли инструмент: только чтение (окружение или UI) → переопределение окружения для инструмента → веб-интерфейс → флаг группы.

Замечания по безопасности

• Ассистент действует от вашего имени через ваш токен — храните его в тайне.

• Разрушительные инструменты выключены по умолчанию. Включайте их осознанно.

• Скачивание произвольного URL по запросу ассистента имеет поверхность для инъекций подсказок. Установите VDL_MCP_DOMAIN_ALLOWLIST (например, youtube.com,instagram.com), чтобы ограничить её.

• Только для контента, который вам принадлежит или на который у вас есть права/разрешение на скачивание — применяется то же предупреждение, что и для vdl.

Лицензия

GNU Affero General Public License v3.0 (AGPL-3.0) — см. LICENSE. © 2026 sphings79