YouTube Knowledge MCP

AI 어시스턴트가 YouTube 동영상을 검색, 분석, 지식 추출할 수 있게 해주는 Model Context Protocol(MCP) 서버입니다. Claude Desktop, Claude Code, Claude.ai, Cursor 및 모든 MCP 호환 클라이언트에서 작동합니다.

로컬(stdio) 및 원격(Streamable HTTP) 전송 방식을 모두 지원합니다.

기능

검색 및 읽기

• 검색 — 키워드로 동영상과 채널 검색

• 가져오기 — 재생 목록 또는 채널에서 동영상 가져오기

• 동영상, 채널, 재생 목록 메타데이터, 챕터, 인기 댓글

• 타임스탬프가 포함된 트랜스크립트 — 시간 범위나 챕터로 잘라내며, 3시간짜리 동영상이 컨텍스트를 넘치게 하지 않도록 상한이 있습니다.

• 트랜스크립트 내부 검색 — 동영상을 해당 지점에서 열어주는 ?t= 링크를 반환

• 일괄 도구: 여러 동영상의 트랜스크립트를 한 번에 가져오거나 전체 재생 목록 요약 생성

편집용 추출

• 시간 범위 클립 — 전체 동영상을 다운로드하지 않고 타임스탬프나 챕터 이름으로 정밀하게 또는 키프레임 기준으로 잘라냅니다

• 오디오 클립 — mp3, m4a, wav, flac 또는 opus 형식

• 프레임 캡처 — 파일을 다운로드하지 않고 특정 타임스탬프에서 캡처

• 자막 내보내기 — Premiere, Resolve 또는 CapCut용 SRT, WebVTT 또는 일반 텍스트

• 전체 다운로드 — 화질 프리셋 지원

배운 내용 보관(로컬 모드)

• 저장 — 요약과 스킬 노트를 로컬 라이브러리에 저장

• 다시 읽기 — 저장된 항목을 다시 읽고 전체 텍스트 순위로 모든 항목 검색

• 태그 추가, 태그 변경, 삭제

채널 브레인 구축(로컬 모드)

• 전체 채널 읽기 — 타임스탬프가 있는 구절로 이루어진 검색 가능한 코퍼스로 변환. 어떤 캡션 언어로든 가능하며, 재개 가능하고 중단해도 안전합니다. 두 번째 실행은 중단된 지점에서 이어서 새 업로드를 수집합니다.

• 크리에이터가 말한 내용 묻기 — 모든 동영상을 통틀어 특정 주제에 대해 물어보면 해당 장면 자체를 링크와 함께 반환받습니다.

• 채널 측정: 읽을 수 있는 양, 업로드 주기, 말하는 속도, 여러 동영상에서 반복되는 표현

• 서면 프로필 유지 — 인용할 수 있는 구절에 근거해 코퍼스 옆에 프로필을 유지

계속 작동하도록 설계

• WebVTT를 수제 매처가 아닌 W3C 표준 구현으로 파싱

• 유형화된 실행 가능한 오류 — yt-dlp stderr의 벽 대신 "no captions in en, try: fr, es, de"

• 모든 yt-dlp 호출에 타임아웃, 백오프 재시도, 동시성 제한 적용

• check_health는 누락되었거나 오래된 yt-dlp와 ffmpeg를 진단

• 모든 도구에 구조화된 출력 제공, MCP 리소스, 프롬프트, completions 지원

Related MCP server: YouTube Translate MCP

사전 요구 사항

• Node.js 22+

• yt-dlp — 모든 도구에 필요합니다. brew install yt-dlp(macOS) 또는 pip install -U yt-dlp

• ffmpeg — 다운로드, 클립 추출, 프레임 캡처에 필요합니다. 그 외에는 ffmpeg 없이도 작동합니다.

둘 다 설치되어 있고 최신인지 확인하려면 check_health 도구를 실행하세요. YouTube가 자주 변경되므로 오래된 yt-dlp가 설명할 수 없는 실패의 가장 흔한 원인입니다. yt-dlp -U로 대부분 해결됩니다.

설치

npm으로 설치(권장)

npm install -g youtube-knowledge-mcp

npx로 설치(설치 불필요)

npx로 직접 구성하세요(Configuration 섹션 참조).

소스에서 설치

git clone https://github.com/teobouancheau/youtube-knowledge-mcp.git
cd youtube-knowledge-mcp
npm install
npm run build

구성

로컬(stdio) — Claude Desktop, Claude Code, Cursor

npx 빠른 시작

{
  "mcpServers": {
    "youtube-knowledge": {
      "command": "npx",
      "args": ["-y", "youtube-knowledge-mcp"]
    }
  }
}

전역 설치 사용

npm install -g youtube-knowledge-mcp

{
  "mcpServers": {
    "youtube-knowledge": {
      "command": "youtube-knowledge-mcp"
    }
  }
}

구성 파일 위치

구성을 업데이트한 후 클라이언트를 다시 시작하세요.

원격(HTTP) — Claude.ai, Claude Mobile, Custom Connectors

서버는 Claude의 공식 커넥터를 통한 원격 액세스를 위해 Streamable HTTP 전송을 지원합니다.

모든 원격 구성은 사용자의 자체 배포입니다. 설계상 커넥터를 가리킬 공유 인스턴스가 없습니다. 모든 호출이 yt-dlp를 셸로 실행하므로, 다른 사람들의 트래픽을 처리하는 단일 호스트는 YouTube가 모두에게 속도 제한을 걸게 됩니다. 아래 버튼을 누르면 클론 없이 약 2분 만에 이 저장소가 사용자의 Render 계정에 배포됩니다.

자체 호스팅

npm run build
npm run start:http

서버는 PORT(기본값 3000)에서 수신합니다. 변경하려면 PORT 환경 변수를 설정하세요.

Docker

docker build -t youtube-knowledge-mcp .

TOKEN=$(openssl rand -hex 32) && echo "MCP_AUTH_TOKEN=$TOKEN"
docker run -p 3000:10000 -e MCP_AUTH_TOKEN="$TOKEN" youtube-knowledge-mcp

토큰은 다른 곳에서 출력되지 않으므로 인쇄됩니다. 서버는 토큰이 필요하다고만 로그에 남기고 값은 절대 남기지 않습니다. Authorization: Bearer $TOKEN으로 보내세요.

이미지는 PORT=10000으로 설정하고 이를 노출합니다. 원하는 호스트 포트로 게시하세요. 빌드는 이미지 내부에서 이루어지므로 먼저 로컬에서 npm run build를 실행할 필요가 없습니다.

Render에 배포

이 버튼은 저장소의 render.yaml을 대상으로 Render의 Blueprint 흐름을 열며, Docker 이미지를 빌드하고 상태 확인을 /health로 지정하며 MCP_AUTH_TOKEN을 생성합니다. 포크도, 클론도, 입력할 설정도 없습니다. 서비스는 계정에 있는, 사용자 소유입니다.

1. 버튼을 클릭하고 확인하세요. Render가 이미지를 빌드하고 배포합니다.

2. 서비스의 Environment 탭을 열고 생성된 MCP_AUTH_TOKEN을 복사하세요. HTTP 전송은 토큰이 없는 모든 요청을 거부하므로, URL이 유출되어도 개방된 서버가 아닙니다.

3. https://<your-service>.onrender.com/mcp를 사용자 지정 커넥터로 추가하고 Authorization: Bearer <token> 헤더를 포함하세요.

서비스가 생성된 후 해두면 좋은 작업: MCP_ALLOWED_HOSTS를 서비스의 호스트 이름(<your-service>.onrender.com)으로 설정하세요. 호스트 이름은 서비스가 생성되어야 존재하므로 Blueprint에서 미리 채울 수 없습니다. 이 설정은 다른 이름으로 들어오는 요청을 거부합니다.

사용자의 인스턴스는 이 저장소를 따라가지 않습니다. Blueprint는 autoDeployTrigger: off로 설정합니다. 자동 배포하면 사용자가 먼저 읽어보지 않은 여기 푸시된 코드가 사용자의 계정에서, 사용자의 토큰으로 실행되기 때문입니다. 최신 버전을 적용하려면 서비스에서 Manual Deploy를 사용하세요.

무료 플랜은 비활성 상태 후 절전 모드로 전환되므로, 중단 후 첫 호출은 콜드 스타트를 기다립니다. 유료 플랜을 사용하면 그런 대기가 없습니다.

Claude.ai로 연결

1. Settings > Connectors로 이동

2. Add custom connector 클릭

3. 서버 URL 입력(예: https://your-app.onrender.com/mcp)

4. MCP_AUTH_TOKEN을 설정한 경우 Authorization: Bearer <token> 헤더를 추가

5. Add 클릭

MCP 도구

33개의 도구가 있습니다. 읽기 전용 14개는 두 전송 방식 모두에서 작동합니다. 파일 시스템에 접근하는 19개는 로컬(stdio) 모드에서만 등록되므로 원격 배포는 호스트 디스크에 접근할 수 없습니다.

모든 도구는 사람이 읽을 수 있는 텍스트와 유형화된 구조화 출력을 반환하며, 실패 시 실행 가능한 메시지로 보고합니다 — [NO_CAPTIONS] No "en" captions are available for this video. Call get_transcript again with one of: fr, es, de.

검색 — 원격 + 로컬

트랜스크립트 — 원격 + 로컬

format: "timestamped"로 설정하면 각 줄 앞에 [MM:SS]가 붙습니다. 특정 순간을 인용하거나 링크로 연결해야 할 때 사용하세요. offset과 함께 maxChars를 사용하면 긴 트랜스크립트를 한 번에 100,000개 이상의 토큰으로 반환하는 대신 여러 조각으로 읽습니다.

편집용 추출 — 로컬 전용

클립은 --download-sections로 잘라내므로 전체 파일이 아닌 해당 구간을 포함하는 바이트 범위만 가져옵니다. preciseCuts(기본값 true)는 요청된 시간에 정확히 잘라냅니다. 더 빠른 키프레임 정렬 컷을 원하면 false로 설정하세요. 이 모든 기능에는 ffmpeg가 필요합니다.

지식 라이브러리 — 로컬 전용

채널 브레인 — 로컬 전용

build_brain은 네트워크에 접근하는 유일한 도구입니다. 나머지는 이미 디스크에 있는 내용에서 채널을 확인하므로 오프라인에서도 작동하며 호출 비용이 들지 않습니다.

브레인은 하나의 자막 언어를 보관합니다. 다른 언어를 읽으려면 language를 전달하고, 언어별로 별도의 브레인을 구축하세요.

since와 minDurationSeconds는 전달한 호출뿐만 아니라 브레인 자체를 설명합니다. 이 값들은 매번 다시 적용되므로, 범위를 좁히면 제외된 동영상의 구절이 삭제되고 넓히면 다시 읽어옵니다. 그래서 build_brain은 파괴적(destructive)으로 표시되어 있습니다. 동영상이 자격을 갖추는지는 이미 기록된 날짜와 길이로 결정되므로, 마음을 바꿔도 새로 가져올 것이 생기기 전까지는 요청 비용이 들지 않습니다. 이러한 값들은 추측이 아닌 각 동영상의 자체 메타데이터에서 비롯됩니다. 평면적인 채널 목록에는 게시 날짜가 전혀 포함되지 않기 때문입니다.

build_brain은 복구도 수행합니다. 구절 파일이 손실되거나 잘린 경우, 더 이상 설명할 수 없는 동영상은 이미 완료된 것으로 영원히 건너뛰지 않고 다음 호출에서 다시 읽습니다.

프롬프트

클라이언트가 직접 호출할 수 있는 재사용 가능한 워크플로우: summarize_video, extract_skill, compare_videos, research_topic, channel_deep_dive, clip_from_quote (문구를 찾은 다음 그 주변으로 클립을 자르기), 그리고 — 로컬 전용 — review_library, create_brain (채널의 말뭉치를 구축한 다음 그것으로 프로필 작성) 및 ask_creator (인용문과 함께 브레인에서 엄격하게 질문에 답변).

리소스

• youtube://transcript/{videoId} — 첫 번째 읽기에서 가져와 캐시되는 타임스탬프가 있는 트랜스크립트

• youtube://library/{videoId}/{summary|skill} — 저장된 노트 (로컬 전용이며 열거 가능)

• youtube://brain/{channelId}/{manifest|profile} — 채널 브레인이 다루는 범위 또는 그로부터 작성된 프로필 (로컬 전용이며 열거 가능)

오류 코드

실패는 모델이 읽고 복구할 수 있도록 결과 안에 보고되며, 각각 코드 접두사와 다음 단계가 뒤따릅니다.

환경 변수

모두 선택 사항입니다.

라이브러리 저장

콘텐츠는 ~/.youtube-knowledge/에 저장됩니다:

~/.youtube-knowledge/
├── transcripts/          # Cached timestamped transcripts
│   └── {video_id}.{lang}.json
├── library/              # Saved notes
│   └── {video_id}/
│       ├── metadata.json
│       ├── summary.md
│       └── skill.md
├── brains/               # Channel brains
│   └── {channel_id}/
│       ├── manifest.json # What the brain covers, and where a build stopped
│       ├── chunks.json   # The timestamped passages
│       └── profile.md    # The written account, if one was saved
├── downloads/            # Full downloads
├── clips/                # Extracted clips
├── frames/               # Captured stills
├── subtitles/            # Exported SRT / VTT / TXT
├── index.json            # Library index
└── search-index.json     # Full-text search index

트랜스크립트는 기본적으로 30일 동안 캐시됩니다. 캐시를 우회하려면 트랜스크립트 도구에 refresh: true를 전달하거나 YOUTUBE_MCP_TRANSCRIPT_TTL_MS를 설정하세요.

파일을 쓰는 모든 도구는 출력을 홈 디렉터리로 제한하며, outputDir이 다른 곳을 가리키면 거부됩니다.

사용 예시

특정 장면을 찾아 인용하기

"Find where this video talks about rate limiting and give me the timestamp:
 https://youtube.com/watch?v=..."

search_transcript는 각 일치 항목을 해당 초에 동영상을 여는 링크와 함께 반환하므로, 주장을 맹신하지 않고 확인할 수 있습니다.

특정 장면을 찾아 클립하기

"Find where she says 'the real bottleneck was the database' and cut me a
 30-second clip around it"

search_transcript가 장면을 찾고 extract_clip이 그것을 자릅니다. 클립을 포함하는 바이트 범위만 다운로드됩니다.

긴 동영상의 한 섹션 읽기

"Summarize just the 'Benchmarks' chapter of this 3-hour podcast"

get_chapters가 섹션을 찾은 다음 chapter: "Benchmarks"와 함께 get_transcript를 사용하면 전체가 아닌 해당 부분만 읽습니다.

재생목록을 저비용으로 살펴보기

"What does this 40-video course cover, and which three videos should I watch?"

digest_playlist는 한 번의 호출로 모든 동영상의 메타데이터와 챕터를 반환합니다.

편집용 푸티지 준비하기

"Pull these four moments as separate clips and export the subtitles as SRT"

extract_clips는 한 번의 호출로 네 개를 모두 자릅니다. export_subtitles는 편집기에서 가져올 수 있는 파일을 작성합니다.

지식 베이스 구축 및 조회

"Summarize this video and save it to my library tagged 'databases'"
"What have I saved about connection pooling?"

save_to_library가 저장하고, search_library는 전체 텍스트 순위로 저장된 모든 항목을 검색합니다.

크리에이터를 위한 브레인 구축

"Build a brain for @Fireship, then tell me everything they've said about Rust"

build_brain은 채널을 타임스탬프된 구절로 읽습니다. 중단한 후 다시 호출하면 이어서 계속됩니다. 그런 다음 ask_brain은 실제로 언급된 내용을 바탕으로 답변하고, 모든 주장을 동영상과 대조해 확인할 수 있도록 해당 장면 자체를 반환합니다. 한 달 후 build_brain을 다시 실행하면 새 업로드만 읽습니다.

테스트

npm test              # Run all tests
npm run test:watch    # Watch mode
npm run test:coverage # Coverage report, with thresholds enforced

테스트 스위트는 순수 로직을 직접 다루고, 인메모리 전송을 통해 MCP 클라이언트로 실제 서버를 구동하며, 실제 임시 파일 시스템에서 라이브러리를 실행하고, 도구 매니페스트를 스냅샷하여 공개 표면의 변경 사항이 검토 가능한 diff로 나타나게 합니다.

개발

npm run dev        # Watch mode
npm run build      # Build for production
npm run rebuild    # Clean and rebuild
npm start          # Run server (stdio)
npm run start:http # Run server (HTTP)
npm run validate   # Typecheck + lint + format check + test

CI는 모든 푸시와 풀 리퀘스트에 대해 Node 22와 24에서 동일한 게이트를 실행한 다음, 빌드된 서버를 실제 MCP 클라이언트로 부팅하여 매니페스트를 검증합니다.

기여

기여를 환영합니다 — 프로젝트 구조, 코딩 표준, 도구 추가 방법은 CONTRIBUTING.md를 참조하세요.

보안

MCP_AUTH_TOKEN을 설정하지 않으면 HTTP 전송은 인증되지 않습니다. localhost 밖으로 노출하기 전에 SECURITY.md를 참조하고, 취약점을 신고하려면 해당 문서를 확인하세요.

라이선스

MIT 라이선스 - 자세한 내용은 LICENSE를 참조하세요.

감사의 말

• yt-dlp — YouTube 추출용

• Anthropic — Model Context Protocol용