vdl-mcp

vdl-mcp는 AI 어시스턴트를 Model Context Protocol을 통해 사용자 소유의 vdl 서버에 연결합니다. 진정한 강점은 Whisper 시너지에 있습니다:

*다운로드 → 전사 → 어시스턴트가 콘텐츠를 이해합니다.*

따라서 다음과 같은 요청을 할 수 있습니다:

• "이 YouTube 동영상을 다운로드하고 요약해 줘."

• "저 요리 클립을 가져와서 레시피를 목록으로 작성해 줘."

• "이 인터뷰에서 X에 대해 뭐라고 했어?"

• "이 강연의 오디오를 다운로드하고 핵심 포인트를 알려줘."

작동 방식

vdl의 REST API와 통신하고 기존 API 토큰으로 인증하는 작은 stdio MCP 서버입니다. vdl 내부에서는 아무것도 실행되지 않습니다.

도구 그룹은 안전한 기본값으로 전환 가능합니다:

비활성화된 그룹은 어시스턴트에게 보이지 않습니다.

Related MCP server: popcorn

요구 사항

• 실행 중인 vdl 인스턴스.

• MCP 토큰: vdl에서 MCP 탭 → 토큰 생성을 열고 복사하세요. 이 토큰은 범위가 지정되어 있습니다. 사용자가 활성화한 MCP 작업만 수행할 수 있습니다(쓰기/삭제 도구는 토글 및 읽기 전용 모드를 따르며, 그 외의 모든 것은 서버 측에서 거부됨). 따라서 일반 API 토큰보다 안전합니다.

설치

pipx 사용 (PATH에 vdl-mcp 추가):

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를 지원하는 모든 클라이언트도 동일하게 작동합니다. stdio를 통해 vdl-mcp 명령을 실행하기만 하면 됩니다.)

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(stdio를 위해 stdin 열기 유지)와 vdl이 동일한 호스트에서 실행될 때 컨테이너가 연결할 수 있도록 host.docker.internal에 유의하세요.

웹 UI 없음 — 의도적 설계

vdl-mcp는 MCP 클라이언트에 의해 로컬에서 실행되는 stdio 프로세스입니다. 네트워크 포트를 열지 않으므로 로그인 페이지나 fail2ban이 없습니다 — 인바운드 보호 대상이 없습니다. 보안 모델은 다음과 같습니다: API 토큰을 비공개로 유지하고, 파괴적 도구를 비활성화(기본값)하며, 선택적으로 도메인 허용 목록을 설정합니다. 인증 및 무차별 대입 공격 방지는 vdl 자체에 있습니다. (원격 다중 클라이언트 HTTP 서버를 원한다면 다른 전송 방식입니다 — 이슈를 열어주세요.)

도구

• resolve(url) — 링크를 분석하고 항목 및 사용 가능한 품질을 나열합니다(다운로드 없음).

• download(url, audio=False, section="", wait=True) — 최고 품질(또는 MP3)을 다운로드합니다. section은 0:30-1:00 같은 클립을 자릅니다. wait는 완료된 파일 name을 반환합니다.

• transcribe(name, language="") — Whisper 전사 → 텍스트를 반환합니다(vdl에 Whisper 모델이 설정되어 있어야 함).

• get_transcript(name) — 기존 전사 텍스트를 반환합니다.

• list_files(query, service, label, limit) — 다운로드를 탐색합니다.

• job_status(job_id) — 다운로드 작업을 확인합니다.

• (기본적으로 꺼짐) delete_file, bulk, get_settings.

구성 (환경 변수)

모든 도구는 설명에 태그가 지정되어 있습니다 — [읽기], [쓰기] 또는 [삭제] — 사용자와 어시스턴트 모두 위험을 한눈에 볼 수 있습니다.

vdl의 웹 UI에서도 관리하세요: vdl에서 설정 → MCP 탭으로 이동하여 각 도구를 전환합니다(읽기 전용 마스터 스위치 및 위험 칩 포함). vdl-mcp는 시작 시 해당 구성을 가져오므로 환경 변수가 필요하지 않습니다. 변경 후 vdl-mcp를 다시 시작하세요. 도구 노출 여부의 우선 순위: 읽기 전용(환경 변수 또는 UI) → 도구별 환경 변수 재정의 → 웹 UI → 그룹 플래그.

보안 참고 사항

• 어시스턴트는 토큰을 통해 사용자로 작동합니다. 비공개로 유지하세요.

• 파괴적 도구는 기본적으로 꺼져 있습니다. 의식적으로 활성화하세요.

• 어시스턴트의 요청에 따라 임의의 URL을 다운로드하는 것은 프롬프트 인젝션 표면이 있습니다. VDL_MCP_DOMAIN_ALLOWLIST(예: youtube.com,instagram.com)를 설정하여 제한하세요.

• 소유하거나 다운로드할 권한/허가가 있는 콘텐츠에만 사용하세요. vdl과 동일한 면책 조항이 적용됩니다.

라이선스

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