claude-video-analyzer

Claude Code가 @video.mp4 첨부만으로 영상을 "보고" 해결하도록 돕는 MCP 서버. 외부 유료 API 불필요 — Claude Code Max 구독자라면 추가 비용 0원.

작동 방식

사용자: "이 영상에서 버그가 발생해 → @bug.mp4"
         ↓
Claude Code → MCP tool: analyze_video(path)
         ↓
claude-video-analyzer (MCP Server, 사용자 머신에서 실행)
    1. ffmpeg로 키프레임 추출 (N초 간격, 최대 60장)
    2. 추출한 프레임을 1280px JPEG로 압축 (~100KB/장)
    3. ffmpeg로 오디오 분리 → WAV 16kHz mono
    4. Transformers.js (로컬 Whisper) → STT (한국어 multilingual)
    5. 타임라인 merge + 마크다운 리포트 + image content 응답
         ↓
Claude Code (사용자 Max 구독)이 image content 직접 분석 + 리포트 읽기

핵심: 프레임은 MCP image content type으로 Claude Code에게 전달되며, Claude는 사용자 Max 구독으로 그 이미지를 직접 봄. 종량제 Anthropic API 호출 0건.

빠른 시작

1. 사전 요구사항

Node.js 20+
ffmpeg — 운영체제별 설치 필요
- macOS: brew install ffmpeg
- Ubuntu/Debian: sudo apt install ffmpeg
- Windows: scoop install ffmpeg 또는 choco install ffmpeg
- 또는 자동 동봉: ffmpeg-ffprobe-static 패키지가 npm install 시 자동 설치됨
Claude Code (CLI 또는 IDE 확장)

2. MCP 서버 등록

macOS/Linux:

claude mcp add claude-video-analyzer --scope user -- npx -y claude-video-analyzer

Windows (Git Bash):

MSYS_NO_PATHCONV=1 claude mcp add-json claude-video-analyzer --scope user '{"command":"cmd","args":["/c","npx","-y","claude-video-analyzer"]}'

등록 확인:

claude mcp list
# claude-video-analyzer: npx ... ✓ Connected

3. Whisper 모델 다운로드 동의

첫 호출 시 로컬 Whisper 모델(base 기준 약 150MB)이 자동 다운로드됩니다. 아래 환경변수로 동의 후 사용:

export CVA_AUTO_DOWNLOAD_MODEL=1

또는 ~/.claude.json의 MCP env에 추가:

{
  "mcpServers": {
    "claude-video-analyzer": {
      "command": "npx",
      "args": ["-y", "claude-video-analyzer"],
      "env": {
        "CVA_AUTO_DOWNLOAD_MODEL": "1"
      }
    }
  }
}

4. 첫 사용

Claude Code 새 세션에서:

이 영상 분석해줘: /path/to/video.mp4

환경변수

변수	필수	기본값	설명
`CVA_AUTO_DOWNLOAD_MODEL`	⚠️ 첫 호출 전	unset	`1`로 설정 시 첫 실행에서 Whisper 모델 자동 다운로드 동의
`WHISPER_MODEL`	❌	`base`	`tiny` / `base` / `small` / `medium` / `large-v3` / `large-v3-turbo` 중 택1
`WHISPER_MODEL_DIR`	❌	`~/.cache/claude-video-analyzer/models/`	모델 캐시 위치
`FFMPEG_PATH`	❌	auto-detect	ffmpeg 바이너리 경로 (PATH 탐색)
`FRAME_INTERVAL_SEC`	❌	`2`	프레임 추출 간격 (초)
`MAX_FRAMES`	❌	`30` (절대 상한 60)	최대 프레임 수

종량제 API 키는 필요 없음. Wave 4 cost-zero pivot 이후 모든 분석이 사용자 머신에서 로컬로 동작.

비용

항목	비용
claude-video-analyzer 패키지	₩0 (MIT OSS)
Claude Code 분석	Max 구독에 포함
Whisper 로컬 STT	₩0 (Transformers.js + Xenova/whisper-base)
모델 다운로드	₩0 (HuggingFace, 1회)
합계	₩0

한국어 정확도

Wave 5에서 Zeroth-Korean 데이터셋으로 측정한 결과는 docs/task/initial-build/wave-5/RESULTS.md 참조. 정확도 향상이 필요하면 WHISPER_MODEL=small (466MB) 또는 WHISPER_MODEL=large-v3-turbo (1.6GB)로 업그레이드.

트러블슈팅

자세한 설치 가이드 + Windows Git Bash MSYS 트러블슈팅: docs/guides/install.md

라이선스

기여

GitHub Issues / Pull Requests 환영. 이 프로젝트는 cost-zero 원칙을 엄격히 준수하므로 종량제 SDK 도입 PR은 거부됩니다 (G1 husky pre-commit hook이 자동 차단).

크레딧

@modelcontextprotocol/sdk — MCP 프로토콜
@huggingface/transformers — Transformers.js (로컬 Whisper)
sharp — 이미지 처리
ffmpeg-ffprobe-static — ffmpeg 바이너리
Zeroth-Korean — 한국어 ASR 평가 데이터셋 (CC BY 4.0, Junbum Lee)