YouTube Video Analyzer MCP

Google Gemini로 공개 YouTube 동영상을 분석하기 위한 MCP stdio 서버입니다.

MCP 호환 클라이언트 어디에서나 사용하여 동영상을 요약하고, 타임스탬프별 인사이트를 추출하고, 음성 콘텐츠를 분석하고, 메타데이터를 확인하고, 긴 VOD를 처리하고, 재사용 가능한 장시간 동영상 세션에 후속 질문을 할 수 있습니다.

제공 기능

• Gemini로 공개 YouTube 동영상 분석.

• 오디오 우선 지침으로 음성 중심 동영상 분석.

• YouTube Data API를 통해 정규화된 YouTube 메타데이터 가져오기.

• yt-dlp 및 ffmpeg로 YouTube 동영상에서 고해상도 JPEG 프레임 추출.

• 필수 MCP 작업을 통한 장시간 동영상 및 VOD 분석.

• MCP 작업을 지원하지 않는 클라이언트를 위한 호환성 백그라운드 작업으로 장시간 동영상 및 VOD 분석.

• 후속 질문을 위한 장시간 동영상 세션 재사용.

• 로컬 다운로드 도구를 사용할 수 없을 때 URL 청킹으로 대체.

• 사용자 지정 응답 스키마를 제공하면 구조화된 JSON 반환.

Related MCP server: YT-NINJA

요구 사항

• Node.js 20 이상.

• Gemini API 키.

• 선택 사항: 메타데이터 조회용 YouTube Data API 키.

• 최상의 장시간 동영상 지원을 위한 선택 사항: yt-dlp 및 ffmpeg.

빠른 시작

게시된 패키지를 MCP 클라이언트에서 npx로 직접 사용하세요:

{
  "mcpServers": {
    "youtube-analyzer": {
      "command": "npx",
      "args": ["-y", "@ludylops/youtube-video-analyzer-mcp"],
      "env": {
        "GEMINI_API_KEY": "your_gemini_key_here",
        "YOUTUBE_API_KEY": "optional_youtube_key_here"
      }
    }
  }
}

GEMINI_API_KEY는 필수입니다. YOUTUBE_API_KEY는 get_youtube_video_metadata에만 필요합니다.

전역 설정

패키지를 전역으로 설치하고 재사용 가능한 구성을 저장할 수도 있습니다:

npm install -g @ludylops/youtube-video-analyzer-mcp
youtube-video-analyzer-mcp setup

그런 다음 MCP 클라이언트에서 다음을 사용할 수 있습니다:

{
  "mcpServers": {
    "youtube-analyzer": {
      "command": "youtube-video-analyzer-mcp"
    }
  }
}

패키지

이 저장소는 소규모 npm 워크스페이스입니다:

• @ludylops/video-analysis-core: packages/video-analysis-core에 있는 재사용 가능한 전송 방식에 독립적인 동영상 분석 로직.

• @ludylops/youtube-video-analyzer-mcp: 저장소 루트에 있는 MCP stdio 서버 어댑터.

MCP 서버는 코어 패키지에 의존하므로 SaaS 앱, CLI, 스킬 및 기타 통합 환경에서 MCP에 의존하지 않고 동일한 분석 로직을 재사용할 수 있습니다.

로컬 개발

npm install
npm run build
npm test
npm start

로컬 실행을 위해 .env.example을 .env로 복사하세요:

GEMINI_API_KEY=your_gemini_api_key_here
YOUTUBE_API_KEY=your_youtube_api_key_here
GEMINI_MODEL=gemini-2.5-pro
YT_DLP_PATH=yt-dlp
MCP_LOG_LEVEL=warn

도구

• get_youtube_analyzer_capabilities: 장시간 동영상 전략에 대한 로컬 지원 여부를 검사합니다.

• get_youtube_video_metadata: 정규화된 공개 YouTube 메타데이터를 가져옵니다.

• get_youtube_video_frame: 타임스탬프에서 고해상도 JPEG 프레임을 추출하며, 로컬 추출 전에 선택적으로 Gemini 타임스탬프 정밀화를 수행합니다.

• analyze_youtube_video: 짧은 동영상 또는 제한된 클립 구간을 분석합니다.

• analyze_youtube_video_audio: 오디오 우선 지침을 사용하여 음성 중심 동영상을 분석합니다.

• analyze_long_youtube_video: 필수 MCP 작업으로 장시간 동영상 또는 VOD를 분석합니다.

• start_long_youtube_analysis: 백그라운드 장시간 동영상 작업을 시작하고 jobId를 반환합니다.

• get_long_youtube_analysis_status: 백그라운드 장시간 동영상 작업을 폴링합니다.

• get_long_youtube_analysis_result: 완료된 백그라운드 장시간 동영상 작업 결과를 가져옵니다.

• cancel_long_youtube_analysis: 백그라운드 장시간 동영상 작업을 취소합니다.

• continue_long_video_analysis: 필수 MCP 작업으로 이전 장시간 동영상 세션에 대한 후속 질문을 합니다.

자세한 입력값, 전략 및 예시는 docs/tools.md를 참조하세요.

장시간 동영상

VOD 및 장시간 동영상의 경우 먼저 get_youtube_analyzer_capabilities를 호출하세요.

기본 장시간 동영상 도구는 MCP 작업 실행이 필요합니다. 클라이언트가 120초와 같은 고정 타임아웃의 동기식 도구 호출만 지원하는 경우 호환성 작업 워크플로우를 사용하세요: start_long_youtube_analysis를 호출하고, get_long_youtube_analysis_status를 폴링한 다음, get_long_youtube_analysis_result를 가져오세요. analyze_youtube_video로 더 짧은 제한된 구간을 분석할 수도 있습니다.

yt-dlp, ffmpeg 및 쓰기 가능한 임시 디렉터리를 사용할 수 있는 경우 strategy=auto 또는 strategy=uploaded_file과 함께 analyze_long_youtube_video를 사용하세요. 이 경로는 재사용 가능한 Gemini 파일 세션을 생성하고 sessionId를 반환할 수 있습니다.

로컬 다운로드 도구를 사용할 수 없는 경우 strategy=url_chunks를 사용하세요. 로컬 미디어 다운로드를 피할 수 있지만 더 많은 Gemini 호출이 필요할 수 있습니다.

전체 가이드는 docs/long-videos.md에서 읽어보세요.

문서

• 설치

• 구성

• 도구

• 장시간 동영상

• 예시

• 문제 해결

• 릴리스 프로세스

• 변경 로그

개인 정보 보호 및 제한 사항

이 서버는 YouTube URL, 프롬프트 및 관련 미디어 또는 파생 청크를 Google Gemini로 보냅니다. strategy=uploaded_file을 사용하면 로컬 도구가 Gemini에 업로드하기 전에 임시 미디어를 다운로드할 수 있습니다. get_youtube_video_frame은 작은 임시 고품질 동영상 구간을 다운로드하고 정확한 JPEG 프레임을 반환합니다. 타임스탬프 정밀화를 요청하면 Gemini는 이미지 픽셀을 생성하는 데 사용되지 않고 타임스탬프를 선택하는 데만 사용됩니다. strategy=url_chunks를 사용하면 서버가 로컬 미디어 다운로드를 피하지만 더 많은 Gemini 호출이 발생할 수 있습니다.

비공개, 삭제된, 연령 제한, 멤버 전용, DRM 보호 또는 지역 차단 동영상은 YouTube 및 Gemini 접근 권한에 따라 실패할 수 있습니다. 사용자는 YouTube 이용약관, Gemini API 이용약관, 저작권 규정 및 현지 법률을 준수할 책임이 있습니다.

프로젝트 구조

• packages/video-analysis-core/src: 재사용 가능한 동영상 분석 코어.

• src/server.ts: MCP 서버 및 도구 등록.

• src/mcp-server-main.ts: stdio 전송 진입점.

• src/platform-runtime: MCP 서버에서 사용하는 런타임 어댑터.

• bin/youtube-video-analyzer-mcp.js: CLI 래퍼 및 설정 흐름.

• src/test: 테스트 스위트.

기여

기여는 언제나 환영합니다. CONTRIBUTING.md부터 시작하고, 변경 사항을 제출하기 전에 npm test를 실행하고, 사용자에게 보이는 동작 변경 사항은 CHANGELOG.md를 업데이트하세요.

라이선스

MIT. LICENSE를 참조하세요.