YouTube Transcript Remote MCP Server

Claude AI가 YouTube 동영상에서 자막을 추출할 수 있게 해주는 최초의 원격 Model Context Protocol (MCP) 서버입니다. 이 서버는 모바일 기기를 포함한 모든 플랫폼의 사용자에게 설치 없이 바로 사용할 수 있는 접근성을 제공합니다.

🌟 주요 기능

• 로컬 설치 불필요: 설치가 필요 없습니다 - 클라우드에서 바로 작동합니다

• 범용 접근성: Claude의 데스크톱, 모바일, 웹 버전에서 모두 작동합니다

• 스마트 캐싱: Cloudflare KV를 활용한 효율적인 캐싱 시스템으로 빠른 응답 제공

• 다국어 지원: 다양한 언어로 자막을 추출할 수 있습니다

• 오류 처리: 사용자 친화적인 메시지와 함께하는 견고한 오류 처리

• 분석 기능: 내장된 요청 추적 및 사용량 분석

• URL 유연성: 모든 YouTube URL 형식 처리 (youtube.com, youtu.be, m.youtube.com 등)

Related MCP server: ytt-mcp

🚀 빠른 시작

옵션 1: 호스팅된 서버 사용 (권장)

가장 간편한 시작 방법 - 공개 서버를 Claude Desktop에 추가하기만 하면 됩니다:

Claude Desktop 사용자용

1. Claude Desktop 설정 열기

   • 메뉴 막대에서 "Claude" 클릭 → "Settings"

   • "Developer" 탭으로 이동

   • "Edit Config" 클릭

2. MCP 서버 구성 추가

   claude_desktop_config.json에 다음을 추가하세요:

   {
     "mcpServers": {
       "youtube-transcript": {
         "command": "npx",
         "args": [
           "mcp-remote",
           "https://youtube-transcript-mcp.ergut.workers.dev/sse"
         ]
       }
     }
   }

3. Claude Desktop 재시작

   구성 파일을 저장한 후 Claude Desktop을 재시작하여 서버를 로드합니다.

4. 설치 확인

   채팅 인터페이스에서 도구 아이콘(🔧)을 찾아보세요. get_transcript 도구가 표시되어야 합니다.

옵션 2: 직접 배포

자체 인스턴스를 실행하고 싶으신가요? 한 번의 클릭으로 Cloudflare Workers에 배포하세요:

또는 수동으로:

git clone https://github.com/ergut/youtube-transcript-mcp
cd youtube-transcript-mcp
npm install
npm run deploy

다른 MCP 클라이언트용

이 서버는 표준 MCP 프로토콜을 지원하며 모든 호환 클라이언트와 함께 사용할 수 있습니다:

• 공개 서버 URL: https://youtube-transcript-mcp.ergut.workers.dev/sse

• 전송 방식: Server-Sent Events (SSE) 또는 HTTP

• 인증: 필요 없음 (공개 서버)

📖 사용 예시

기본 자막 추출

Extract the transcript from this YouTube video: https://www.youtube.com/watch?v=dQw4w9WgXcQ

다국어 지원

Can you get the transcript of this video in Turkish: https://youtu.be/VIDEO_ID

Extract the Spanish transcript from: https://www.youtube.com/watch?v=VIDEO_ID

지원되는 URL 형식

서버는 모든 YouTube URL 형식을 자동으로 처리합니다:

• https://www.youtube.com/watch?v=VIDEO_ID

• https://youtu.be/VIDEO_ID

• https://m.youtube.com/watch?v=VIDEO_ID

• https://www.youtube.com/live/VIDEO_ID

• https://www.youtube.com/embed/VIDEO_ID

• https://www.youtube.com/shorts/VIDEO_ID

• 국제 도메인 (youtube.co.uk, youtube.de 등)

모든 추적 매개변수(예: ?si=, &t= 등)는 자동으로 제거됩니다.

🛠 사용 가능한 도구

get_transcript

YouTube 동영상 URL에서 자막을 추출합니다.

매개변수:

• url (필수): 모든 형식의 YouTube 동영상 URL

• language (선택): 자막의 언어 코드 (예: 'en', 'es', 'fr'). 기본값은 'en'입니다.

사용 예시:

{
  "name": "get_transcript",
  "arguments": {
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "language": "en"
  }
}

🔧 고급 구성

디버그 로깅

문제 해결을 위한 상세 로깅 활성화:

{
  "mcpServers": {
    "youtube-transcript": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://youtube-transcript-mcp.ergut.workers.dev/sse",
        "--debug"
      ]
    }
  }
}

디버그 로그는 ~/.mcp-auth/{server_hash}_debug.log에 생성됩니다.

HTTP 전송 전용

SSE 대신 HTTP 전송을 강제하려면:

{
  "mcpServers": {
    "youtube-transcript": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://youtube-transcript-mcp.ergut.workers.dev/mcp",
        "--transport",
        "http-only"
      ]
    }
  }
}

📊 서버 정보

• 호스팅: Cloudflare Workers

• 캐싱: 성공적인 자막에 대해 7일 캐시를 제공하는 Cloudflare KV

• 속도 제한: 지수 백오프가 내장된 재시도 로직

• 가동 시간: Cloudflare의 글로벌 네트워크를 통한 99.9%+ 가용성

• 응답 시간: 캐시된 콘텐츠는 일반적으로 3초 미만, 새 요청은 10초 미만

🚨 오류 처리

서버는 일반적인 문제에 대해 명확한 오류 메시지를 제공합니다:

• "Invalid YouTube URL provided": URL 형식이 인식되지 않음

• "No transcript available for this video": 동영상에 자막/트랜스크립트가 없음

• "Video not found or private": 동영상이 비공개, 삭제되었거나 존재하지 않음

• "Service temporarily busy, try again in a few minutes": YouTube의 속도 제한

• "Transcripts are disabled for this video": 제작자가 자막을 비활성화함

🌍 언어 지원

서버는 YouTube가 자막을 제공하는 모든 언어를 지원합니다. 일반적인 언어 코드:

• en - 영어 (기본값)

• tr - 터키어

• es - 스페인어

• fr - 프랑스어

• de - 독일어

• it - 이탈리아어

• pt - 포르투갈어

• ja - 일본어

• ko - 한국어

• zh - 중국어

🔒 개인정보 및 보안

• 인증 불필요: 사용 편의성을 위한 공개 서버

• 데이터 저장 없음: 자막은 성능 향상을 위해 일시적으로만 캐시됩니다

• 개인정보 수집 없음: YouTube 동영상 ID와 자막만 처리됩니다

• HTTPS 전용: 모든 통신이 암호화됩니다

• CORS 활성화: 웹 기반 MCP 클라이언트 지원

🚀 API 엔드포인트

직접 통합하려는 개발자를 위한 정보:

HTTP POST /mcp

직접 통합을 위한 표준 MCP JSON-RPC 엔드포인트.

Server-Sent Events /sse

실시간 통신을 위한 MCP SSE 전송 엔드포인트.

Info /

서버 정보 및 상태 엔드포인트.

직접 API 호출 예시:

curl -X POST https://youtube-transcript-mcp.ergut.workers.dev/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_transcript",
      "arguments": {
        "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
        "language": "en"
      }
    }
  }'

🐛 문제 해결

일반적인 문제

1. Claude Desktop에서 "Connection Error" 발생

   • 최신 버전의 Claude Desktop을 사용 중인지 확인하세요

   • mcp-remote가 올바르게 구성되었는지 확인하세요

   • 상세 로그를 보려면 --debug 플래그를 추가해 보세요

2. "Could not attach to MCP server" 발생

   • 인터넷 연결을 확인하세요

   • 서버 URL이 올바른지 확인하세요

   • 구성 변경 후 Claude Desktop을 재시작하세요

3. 자막이 반환되지 않음

   • YouTube URL이 유효하고 접근 가능한지 확인하세요

   • 동영상에 자막이 활성화되어 있는지 확인하세요

   • 가능한 경우 다른 언어 코드를 시도해 보세요

도움 받기

• 로그 확인: ~/.mcp-auth/에서 디버그 로그를 확인하세요

• 직접 연결 테스트: npx -p mcp-remote@latest mcp-remote-client https://youtube-transcript-mcp.ergut.workers.dev/sse 사용

• 서버 상태 확인: https://youtube-transcript-mcp.ergut.workers.dev/ 방문

• 이슈 등록: GitHub Issues

🤝 기여

이 프로젝트는 오픈소스입니다. 기여를 환영합니다!

• 이슈 보고: 버그를 발견하셨나요? 이슈를 등록해 주세요

• 기능 요청: 개선 아이디어가 있으신가요? 알려주세요!

• 코드 기여: 개선을 위한 PR을 환영합니다

개발 환경 설정

git clone https://github.com/ergut/youtube-transcript-mcp
cd youtube-transcript-mcp
npm install
npm run dev

📜 라이선스

이 프로젝트는 오픈소스이며 MIT License에 따라 사용할 수 있습니다.

🙏 감사의 말

• Anthropic의 Model Context Protocol로 구축됨

• Cloudflare Workers에서 호스팅됨

• youtube-transcript 라이브러리 사용

• MCP 커뮤니티와 기존 로컬 자막 서버에서 영감을 받음

Claude에 YouTube 자막 추출 기능을 더할 준비가 되셨나요? 이 서버를 Claude Desktop 구성에 추가하고 어떤 YouTube 동영상에서든 즉시 자막을 추출해 보세요! 🎉