YouTube Downloader MCP

ChatGPT 웹에서 YouTube 영상, 음원, 재생목록을 MP4/MP3로 준비하는 원격 MCP App입니다. ~/Desktop/ytdl_cli의 yt-dlp + ffmpeg 방식을 서버용으로 옮기고, ChatGPT 채팅 안에 실시간 진행 화면과 미디어 플레이어가 나타나는 MCP Apps 위젯을 추가했습니다.

제공 도구

• inspect_youtube_url: 영상/재생목록 자동 감지, 제목, 곡 수, 항목 목록 확인

• start_download: 단일 영상/음원의 비동기 작업 시작

• start_playlist_download: 재생목록 전체를 원래 순서대로 하나씩 다운로드

• retry_download: 재생목록 처리가 끝난 뒤 실패한 항목 하나를 다시 시도

• connect_google_drive: 브라우저에 암호화 저장된 Drive 연결 복원

• load_drive_downloads: Drive 전용 폴더의 최근 다운로드 내역 복구

• load_drive_file: 고유 파일명으로 Drive 파일 하나 복구

• get_download_status: 개별 항목 진행률 조회

• get_batch_status: 전체 및 모든 항목의 최신 상태 조회

• render_download_widget: 채팅 안에 실시간 진행 UI와 플레이어 표시

위젯은 1초마다 자동 갱신하며 각 항목의 받은 용량, 전체 예상 용량, 속도, ETA, 진행률과 상태를 보여줍니다. 배치·영상·마지막 진행 상태는 브라우저 localStorage에도 저장하므로 채팅을 다시 열 때 화면부터 즉시 복원합니다. 완료 파일은 Google Drive의 YouTube Downloader MCP 폴더에 한 개씩 업로드되고, 업로드 직후 Render 임시 파일은 삭제됩니다. 각 파일에는 고유 파일명이 붙으므로 서버 재시작 뒤에도 최근 내역이나 고유 파일명으로 다시 찾을 수 있습니다.

완료된 MP4/MP3는 위젯에서 개별 다운로드하거나 이동·크기 조절 가능한 미리보기로 재생할 수 있습니다. 모든 항목의 처리가 끝나면 성공한 파일 전체를 스트리밍 ZIP으로 받을 수 있고, 실패 항목을 재시도하는 동안에는 전체 다운로드가 다시 잠깁니다. 앱에서 정한 파일 용량 상한은 없으며, 다운로드는 서버 부담을 줄이기 위해 한 번에 1개씩 순서대로 처리합니다. Drive 인증 후 작업은 위젯 폴링과 분리된 백엔드 스레드에서 실행되므로 채팅을 닫아도 서버 프로세스가 살아 있는 동안 계속됩니다. 라이브 스트림은 지원하지 않습니다.

애플리케이션의 용량 제한을 없애도 호스팅 서버의 디스크·메모리·대역폭 한계는 없어지지 않습니다. 특히 무료 Render 인스턴스는 대용량 영상과 큰 재생목록을 안정적으로 처리하는 무제한 저장소가 아닙니다.

Related MCP server: LLM Jukebox

로컬 실행

Python 3.10 이상과 ffmpeg가 필요합니다.

cd ~/Desktop/ytdl_mcp
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
ALLOWED_HOSTS=localhost,127.0.0.1 \
  .venv/bin/uvicorn server:app --host 127.0.0.1 --port 8000

• MCP URL: http://127.0.0.1:8000/mcp

• 상태 확인: http://127.0.0.1:8000/health

MCP Inspector에서는 전송 방식을 Streamable HTTP로 선택합니다.

npx @modelcontextprotocol/inspector

Render 무료 배포

1. 이 폴더를 새 GitHub 저장소에 push합니다.

2. Render에서 New → Blueprint를 선택하고 저장소를 연결합니다.

3. 환경 변수를 다음처럼 설정합니다.

   • PUBLIC_BASE_URL=https://서비스이름.onrender.com

   • ALLOWED_HOSTS=서비스이름.onrender.com

   • MAX_CONCURRENT_JOBS=1

   • JOB_TTL_SECONDS=1800

   • YTDLP_COOKIE_FILE=/etc/secrets/youtube-cookies.txt

   • GOOGLE_DRIVE_CLIENT_ID=Google OAuth 웹 클라이언트 ID

   • GOOGLE_DRIVE_CLIENT_SECRET=Google OAuth 클라이언트 보안 비밀

   • GOOGLE_DRIVE_SETUP_TOKEN=Render의 Generate로 만든 긴 임의 문자열

   • GOOGLE_DRIVE_FOLDER_NAME=YouTube Downloader MCP

   • SELF_KEEPALIVE_ENABLED=true

   • SELF_KEEPALIVE_INTERVAL_SECONDS=420

   GOOGLE_DRIVE_REFRESH_TOKEN은 선택 사항입니다. 위젯 로그인 방식을 쓰면 비워 둬도 되고, 서버에 고정 연결할 때만 Render 비밀 환경 변수로 설정합니다.

4. YouTube가 서버 요청에 로그인을 요구한다면 Render의 Environment → Secret Files → Add Secret File에서 다음 파일을 추가합니다.

   • Filename: youtube-cookies.txt

   • Contents: Netscape 형식으로 내보낸 youtube.com 쿠키 내용

   쿠키 파일은 GitHub나 일반 환경 변수에 넣지 마세요. 서버는 Render의 읽기 전용 비밀 파일을 작업마다 별도의 임시 파일로 복사해 사용하며, 임시 파일은 작업 종료 시 삭제합니다. 배포 Docker 이미지에는 최신 YouTube JavaScript challenge 처리를 위한 Deno와 yt-dlp-ejs도 포함됩니다.

5. 배포 후 다음 주소를 확인합니다.

   • 상태: https://서비스이름.onrender.com/health

   • MCP: https://서비스이름.onrender.com/mcp

/health의 youtube.cookies_configured가 true, youtube.js_runtime이 "deno"이면 서버가 쿠키와 JavaScript 런타임을 인식한 것입니다.

YouTube 쿠키 내보내기

YouTube 계정 쿠키는 비밀번호와 비슷한 비밀정보입니다. 필요한 경우에만 다음처럼 내보내세요.

1. 브라우저의 새 시크릿/비공개 창 하나만 열고 YouTube에 로그인합니다.

2. 같은 탭에서 https://www.youtube.com/robots.txt로 이동합니다.

3. 신뢰할 수 있는 로컬 전용 도구로 youtube.com 쿠키만 Netscape cookies.txt 형식으로 내보냅니다.

4. 곧바로 시크릿/비공개 창을 닫고, 내보낸 내용을 Render Secret File에 youtube-cookies.txt라는 이름으로 붙여 넣습니다.

5. 로컬 쿠키 파일은 Render 설정 완료 후 안전하게 삭제합니다.

계정 쿠키를 사용하면 YouTube 계정이 일시적 또는 영구적으로 제한될 위험이 있습니다. 요청량을 낮게 유지하고 본계정 쿠키를 서버에 보관하는 것은 피하는 것이 안전합니다. 쿠키를 교체하면 Render에서 다시 배포한 뒤 상태 주소를 확인하세요.

활성 다운로드나 Drive 업로드가 있으면 서버가 7분마다 자신의 /health에 요청해 무료 인스턴스의 유휴 정지를 방지하려고 시도합니다. 작업이 없으면 자가 요청도 자동으로 멈춥니다. 다만 Render가 자가 요청을 항상 활동으로 인정한다고 보장하지 않고 무료 인스턴스를 임의로 재시작할 수도 있으므로, 실행 중 작업의 절대적인 지속성을 보장하는 장치는 아닙니다. 이미 Drive에 업로드된 파일은 영향을 받지 않습니다.

Google Drive OAuth 설정

1. Google Cloud Console에서 프로젝트를 만들고 Google Drive API를 활성화합니다.

2. OAuth 동의 화면을 구성합니다. 앱이 테스트 모드라면 사용할 Google 계정을 테스트 사용자로 추가합니다.

3. OAuth client ID → Web application을 만듭니다.

4. 승인된 리디렉션 URI에 다음 주소를 정확히 추가합니다.

   https://서비스이름.onrender.com/drive/callback

5. 발급된 Client ID와 Client secret을 Render 환경 변수에 입력하고 다시 배포합니다.

6. ChatGPT에서 다운로드를 처음 시작하면 위젯의 Google 계정으로 로그인을 누릅니다. 서버는 drive.file 범위만 요청하고, 로그인 성공 즉시 YouTube Downloader MCP 폴더를 검색해 없으면 자동 생성합니다.

로그인 후 브라우저에는 원본 OAuth refresh token이 아니라 GOOGLE_DRIVE_SETUP_TOKEN으로 암호화한 연결값만 저장됩니다. 새 채팅이나 오래된 채팅을 열면 위젯이 이 값을 이용해 Drive 연결과 최근 내역을 자동 복구합니다.

ChatGPT 웹에 연결

ChatGPT 웹의 Settings → Apps → Advanced settings → Developer mode를 켠 뒤, 새 앱/커넥터의 원격 MCP URL로 https://서비스이름.onrender.com/mcp를 입력합니다. 계정 플랜과 워크스페이스 관리자 정책에 따라 메뉴와 허용 범위가 다를 수 있습니다.

예시 요청:

이 영상을 720p MP4로 준비해 줘: https://youtu.be/...

재생목록 예시:

이 재생목록을 각 항목 192kbps MP3로 준비하고 진행 화면을 보여줘: https://www.youtube.com/playlist?list=...

Drive 내역 예시:

Google Drive에 저장된 최근 다운로드 20개를 진행 화면으로 보여줘.

고유 파일명으로 찾기:

고유 파일명 AbCd123__example.mp4 파일을 Google Drive에서 불러와줘.

ChatGPT는 시작 도구 호출 후 render_download_widget을 호출합니다. 이후 위젯이 get_batch_status를 1초마다 직접 호출하므로 ChatGPT 답변을 계속 새로 만들지 않고 카드 내부의 진행 상태만 자연스럽게 갱신합니다.

운영 전 필수 보안

현재 구성은 개인 개발 테스트용입니다. URL을 아는 누구나 작업을 만들 수 있으므로 공개 배포·공개 등록 전에는 OAuth 2.1 사용자 인증, 사용자별 할당량, 외부 작업 저장소/오브젝트 스토리지, 모니터링을 추가해야 합니다.