YouTube Transcript & Search MCP Server

🎬 왜?

이미 에이전트와 함께 작업해 본 사람이라면 이 대화를 한 번쯤은 겪어봤을 것입니다.

You:   Summarize this. https://www.youtube.com/watch?v=kCc8FmEb1nY
Agent: I'm not able to watch videos. If you paste the transcript here, I'll gladly help!

트랜스크립트는 정확히 에이전트가 스스로 얻을 수 없는 대상입니다. 이 서버를 연결하면 같은 메시지는 그냥 해결됩니다.

You:   Summarize this. https://www.youtube.com/watch?v=kCc8FmEb1nY
Agent: → get_transcript(video="kCc8FmEb1nY", video_metadata=true)      1 credit

       That's "Let's build GPT: from scratch, in code, spelled out" by Andrej
       Karpathy, 1:56:20. He starts from an empty file and a bigram model,
       derives self-attention step by step, and ends with a working GPT that...

동영상 하나를 읽는 것으로 작업이 끝나는 경우는 거의 없습니다. YouTube 데이터를 에이전트에 가져오는 세 가지 방법을 실제로 비교하면 다음과 같습니다.

Related MCP server: VidLens

⚡ 빠른 시작

1. API 키를 발급받으세요. transcriptout.com에서 가입하고 dashboard에서 키를 생성하세요. 새로운 계정에는 무료 크레딧 100개가 지급되며 카드는 요구하지 않습니다. 키는 sk_로 시작하며 한 번만 보여줍니다.

2. 클라이언트를 서버에 연결하세요. 서버는 streamable HTTP를 사용하며, 단일 Bearer 인증 헤더로 인증됩니다.

{
  "mcpServers": {
    "transcriptout": {
      "url": "https://api.transcriptout.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Cursor와 VS Code용 원클릭 버튼은 이 페이지 상단에 있습니다. 나머지 클라이언트를 위한 정확한 설정 코드는 클라이언트 설치 섹션에 있습니다.

3. 링크를 붙여넣습니다.

Summarize this talk and pull the three strongest quotes.
https://www.youtube.com/watch?v=dQw4w9WgXcQ

에이전트는 get_transcript를 자체적으로 골라서 timed text를 읽고 그에 따라 답변합니다. 모든 응답에는 X-Credits-Remaining 헤더가 포함되므로 세션 내내 예산을 확인할 수 있습니다.

🧰 14가지 도구

연결만 하면 14개 도구가 자동으로 제공됩니다. 대부분의 호출은 1크레딧입니다. 크레딧은 호출이 YouTube에 도달하기 전에 실패하는 경우(유효성 검사 오류, rate limit, 서버 용량 문제) 자동으로 환급됩니다. 즉, 실패가 아니라 답변에 대해 비용을 냅니다. "이 동영상에는 자막이 없다"는 확정적인 답변도 답변이므로 동일하게 청구됩니다.

1. get_transcript · 1크레딧

모든 YouTube 동영상의 트랜스크립트를 가져옵니다. format=text(기본값)는 사람이 읽을 수 있는 텍스트를 반환하고, format=json은 시간 정보가 있는 세그먼트를 반환합니다.

지정하지 않으면 segment는 자동 생성 트랙을 ~180자 세그먼트로 자르고, 수동 트랙은 원작자가 나눈 그대로 반환합니다. 어떤 트랙이 응답하든 하나의 크기로 통일해야 한다면 이 값을 지정하세요.

예시 출력 (format=json):

{
  "video_id": "dQw4w9WgXcQ",
  "language": "en",
  "kind": "manual",
  "transcript": [
    { "text": "Never gonna give you up", "start": 18.0, "duration": 4.12 },
    { "text": "Never gonna let you down", "start": 22.12, "duration": 3.85 }
  ]
}

srt와 vtt는 완전한 자막 파일 본문으로 반환되어 에이전트가 그대로 파일로 저장하면 됩니다. srv3은 YouTube 원본 XML이며 segment과 함께 사용할 수 없습니다.

2. get_video_info · 1크레딧

하나의 동영상에 대한 메타데이터(제목, 채널, 재생 시간, 조회수, 썸네일)와 사용 가능한 트랜스크립트 언어 목록을 반환합니다. 자막 다운로드는 하지 않습니다.

크레딧 관리: 어차피 트랜스크립트를 가져올 예정이라면 get_transcript을 `video_metadata=true와 함께 호출하는 것이 좋습니다. 두 번의 호출과 두 크레딧을 쓰는 대신, 1크레딧으로 두 가지 정보를 모두 얻을 수 있습니다.

3. search_youtube · 1크레딧/페이지

YouTube에서 동영상 또는 채널을 검색합니다. next_page_token으로 페이지네이션하고 has_more로 다음 페이지 존재 여부를 알려줍니다.

4. list_channel_videos · 1크레딧/페이지

채널의 Videos 탭에서 동영상 목록을 최신 최신순으로 가져옵니다. @handle, 채널 이름, UC... 채널 ID 또는 채널 URL을 허용합니다.

ids_only=true는 submit_transcripts_job에 공급할 ID 목록을 저비용으로 확보하는 핵입니다.

5. search_channel_videos · 1크레딧/페이지

YouTube의 기본 관련성 검색을 통해 채널 내부를 검색합니다. 결과 제목에 검색어가 없을 수 있는 것은 정상입니다. 결과는 부분 문자열 일치가 아닌 관련성 순으로 정렬됩니다.

6. latest_channel_videos · 1크레딧

채널 RSS 피드에서 최근 동영상 약 ~15개를 가져옵니다. 채널이 최근에 올린 콘텐츠를 확인하는 가장 빠르고 저렴한 방법입니다.

7. list_playlist_videos · 1크레딧/페이지

재생목록의 모든 동영상을 playlist 목록 순서로 반환합니다. PL... 재생목록 ID 또는 list=가 포함된 URL을 허용합니다.

8. search_playlist_videos · 1크레딧

재생목록 안에서 제목의 부분 문자열(대소문자 구분 없음)로 동영상을 찾습니다. YouTube에는 기본 재생목록 검색이 없으므로 재생목록 항목을 최대 500개까지 검사합니다. truncated=true는 검사된 범위 밖에 더 많은 일치 결과가 있을 수 있음을 의미합니다.

9. submit_transcripts_job · 동영상당 1 크레딧

한 번에 많은 동영상(최대 4,000개)의 트랜스크립트를 대기열에 넣고 즉시 job_id를 받습니다. 작업은 백그라운드에서 요금 한도(rate limit)의 속도에 맞춰 계속 진행됩니다. 소수의 동영상보다 많은 동영상에 대해 get_transcript를 반복 호출하는 대신 이 도구를 사용하세요.

사용자 키(sk_...)가 필요합니다. 크레딧은 제출 시 차감되며, 우리의 과실로 동영상을 전달하지 못한 경우 동영상별로 환불됩니다.

10. get_transcripts_job · 무료

배치 작업의 진행 상태: 상태(queued/running/done/cancelled), 준비된 동영상 수, 실패 및 대기 수. 이미 결제한 작업을 폴링하는 것은 비용이 들지 않습니다.

11. get_transcripts_result · 무료

배치 작업에서 완료된 트랜스크립트를 제출 순서대로 반환하며, next_page_token의 페이지로 나눠 제공됩니다(limit 1–500, 기본 100). 결과가 수신되는대로 나타나므로 작업이 끝나기 전에 읽을 수 있습니다. 각 항목은 get_transcript가 해당 동영상에 대해 반환하는 것과 정확히 동일하며, 상태 정보도 포함합니다.

12. get_transcripts_result · 무료

배치 작업에서 특정 동영상의 결과를, 전체 결과를 페이지로 나누지 않고 동영상 ID로 조회합니다. 404가 반환되면 작업이 존재하지 않거나 해당 동영상이 아직 완료되지 않았으므로, 결론 내리기 전에 get_transcripts_job을 확인하세요.

13. cancel_transcripts_job · 무료

배치 작업을 취소합니다. 크레딧은 아직 시작되지 않은 동영상에 대해서만 환불됩니다. 이미 가져온 항목은 결과에 남아 있으며 결제된 상태가 유지됩니다.

14. get_credits · 무료

매개변수 없이 해당 키의 남은 크레딧 잔액을 반환합니다. 잔액은 모든 응답의 X-Credits-Remaining 헤더에도 포함되지만, 헤더는 모델에게 보이지 않습니다. 사용자가 실제로 묻는 이 숫자에는 도구가 필요합니다. 큰 배치 작업 직전에도 유용하며, 배치는 제출 시 동영상당 1크레딧이 청구됩니다.

🔌 클라이언트에 설치

서버는 원격에 있으므로 아래의 모든 설치는 구성 항목만 추가하는 것입니다. 모두 동일한 두 가지 값, 즉 Quick start의 URL과 Bearer 헤더가 필요합니다.

클라이언트에 한 번만 설정하면 되는, 고정 규칙

클라이언트의 규칙/지침에 이 내용을 포함하면 YouTube 링크를 붙여넣는 것만으로 충분하며, "transcript"라는 단어를 입력할 필요가 없습니다:

Whenever a YouTube link or video ID appears in my message, call the
transcriptout get_transcript tool first and answer from the transcript,
whether I asked for a summary, a quote, a translation or a question.

원클릭 설치:

설치 후 서버 설정을 열고 Authorization 헤더에 키를 추가하세요.

수동 구성 (~/.cursor/mcp.json):

{
  "mcpServers": {
    "transcriptout": {
      "url": "https://api.transcriptout.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

claude mcp add --transport http transcriptout https://api.transcriptout.com/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Claude의 커스텀 커넥터는 원격 서버를 OAuth로 인증하지만, TranscriptOut은 아직 OAuth를 지원하지 않습니다(API 키만 지원). 데스크톱에서는 API 키 헤더를 지원하는 Claude Code를 사용하세요(위 참조). OAuth 지원은 로드맵에 있으며 changelog를 참조하세요.

또는 VS Code 설정(settings.json)에 다음을 추가하세요:

"mcp.servers": {
  "transcriptout": {
    "type": "http",
    "url": "https://api.transcriptout.com/mcp",
    "headers": {
      "Authorization": "Bearer YOUR_API_KEY"
    }
  }
}

1. 새 Agent를 만듭니다.

2. Actions 또는 Tools에서 새 MCP Server를 추가합니다.

3. URL: https://api.transcriptout.com/mcp

4. 인증 유형: API Key

5. dashboard에서 API 키를 붙여넣습니다.

~/.codeium/windsurf/mcp_config.json에 추가:

{
  "mcpServers": {
    "transcriptout": {
      "serverUrl": "https://api.transcriptout.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "transcriptout": {
      "url": "https://api.transcriptout.com/mcp",
      "type": "streamableHttp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Zed의 settings.json에 추가:

{
  "context_servers": {
    "transcriptout": {
      "source": "remote",
      "url": "https://api.transcriptout.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "transcriptout": {
      "type": "streamable-http",
      "url": "https://api.transcriptout.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

amp mcp add transcriptout https://api.transcriptout.com/mcp --header "Authorization: Bearer YOUR_API_KEY"

settings.json의 augment.advanced 아래에 추가:

"augment.advanced": {
  "mcpServers": [
    {
      "name": "transcriptout",
      "url": "https://api.transcriptout.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  ]
}

.kilocode/mcp.json에 추가:

{
  "mcpServers": {
    "transcriptout": {
      "type": "streamable-http",
      "url": "https://api.transcriptout.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Settings → Tools → AI Assistant → MCP에서 추가:

{
  "mcpServers": {
    "transcriptout": {
      "url": "https://api.transcriptout.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

~/.gemini/settings.json에 추가:

{
  "mcpServers": {
    "transcriptout": {
      "httpUrl": "https://api.transcriptout.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

~/.qwen/settings.json에 추가:

{
  "mcpServers": {
    "transcriptout": {
      "httpUrl": "https://api.transcriptout.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "transcriptout": {
      "serverUrl": "https://api.transcriptout.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "transcriptout": {
      "url": "https://api.transcriptout.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

mcp.json에 추가:

{
  "mcpServers": {
    "transcriptout": {
      "url": "https://api.transcriptout.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Settings → AI → MCP에서 추가:

{
  "transcriptout": {
    "url": "https://api.transcriptout.com/mcp",
    "headers": {
      "Authorization": "Bearer YOUR_API_KEY"
    }
  }
}

Settings → Connectors → Advanced에서 추가:

{
  "url": "https://api.transcriptout.com/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_API_KEY"
  }
}

🧩 Agent Plugin으로 설치

본 리포지토리의 최상위 루트는 Agent Plugins 1.0.0 표준을 따르는 패키지입니다. 이는 ChatGPT, Codex, Cursor, GitHub Copilot, Kiro, VS Code가 지원하는 이식 가능한 형식입니다. 한 번만 설치하면 MCP 서버와 함께, 어떤 도구를 언제 사용하고 크레딧을 낭비하지 않는 방법을 에이전트에게 알려주는 youtube 스킬이 번들로 제공됩니다.

plugin.json                # manifest
mcp.json                   # hosted MCP server, streamable-http
skills/youtube/SKILL.md    # when + how to use the 14 tools

VS Code. 명령 팔레트를 연 다음 Chat: Install Plugin From Source를 선택하고 붙여넣기:

https://github.com/artemchuikin/youtube-mcp

또는 로컬 복제본을 settings.json에 등록:

"chat.pluginLocations": { "/absolute/path/to/youtube-mcp": true }

Cursor. 사이드바에서 Customize → 플러그인을 찾아 Install을 클릭합니다. 로컬 복제본인 경우:

git clone https://github.com/artemchuikin/youtube-mcp ~/.cursor/plugins/local/transcriptout

그런 다음 Developer: Reload Window를 실행하세요.

ChatGPT, Codex, GitHub Copilot, Kiro 등 다른 클라이언트. 클라이언트의 플러그인 메커니즘을 이 리포지토리 또는 로컬 복제본을 공유하세요. Agent Plugins 1.0.0은 패키지 형식을 표준화할 뿐 설치 방식은 표준화하지 않으므로, 각 클라이언트가 별도의 설치 방식을 가집니다.

이 패키지에는 자격 증명이 포함되어 있지 않습니다. Agent Plugins 1.0.0은 임베디드 시크릿을 금지합니다. 서버는 클라이언트의 MCP 설정에서 추가하는 API 키로 인증됩니다 (Keys and security 참조). 직접 패키지를 검증하세요:

curl -sO https://agent-plugins.org/schemas/1.0.0/plugin.schema.json
curl -sO https://agent-plugins.org/schemas/1.0.0/mcp.schema.json
npx ajv-cli@5 validate --spec=draft2020 -s plugin.schema.json -d plugin.json
npx ajv-cli@5 validate --spec=draft2020 -s mcp.schema.json    -d mcp.json

🔑 키와 보안

• 키는 생성 시 한 번만 표시됩니다. 환경 변수에 보관하고 버전 관리 밖에 두세요.

• 유출된 키는 dashboard에서 취소되면 즉시 더 이상 작동하지 않습니다. 계정은 최대 20개의 키를 보유할 수 있으므로 각 기기마다 키를 별도로 발급하세요.

• 채팅에서 관리하고 싶으신가요? 함께 제공되는 youtube-skills 이 설치된 에이전트가 이메일과 6자리 코드만으로 브라우저 없이 계정을 열고 키를 발급해 줄 수 있습니다.

• 아직 OAuth 흐름이 없으므로, 커스텀 헤더를 보낼 수 없는 커넥터(Claude Desktop, Claude Web)를 사용하는 클라이언트은 지금은 Claude Code를 이용하면 됩니다.

🐳 로컬에서 실행하기

호스트된 엔드포인트는 추가 설치가 필요 없습니다. 하지만 stdio 전용 클라이언트, 샌드박스, 컨테이너 플랫폼은 자체 프로세스가 필요할 수 있습니다. 이 리포지토리에는 그런 실행 파일이 포함되어 있습니다. `server[/code]는 완전한 로컬 MCP 서버(공식 SDK, stdio transport)이며, 14개 도구가 TranscriptOut REST API로 HTTPS 요청을 각각 한 번 수행합니다. 이는 SaaS에 지원되는 MCP 서버의 일반적인 구조와 같습니다.

# as a container
docker build -t transcriptout-mcp https://github.com/artemchuikin/youtube-mcp.git
docker run -i -e TRANSCRIPTOUT_API_KEY=sk_your_key transcriptout-mcp

# or straight from a checkout (Node 20+)
npm install && TRANSCRIPTOUT_API_KEY=sk_your_key node server.js

키가 없음에도 연결은 되고 모든 도구가 나열됩니다. 도구를 호출하면 명확한 401 응답과 함께 키를 얻을 수 있는 위치를 안내합니다. 도구 정의는 tools.json에 포함되어 있으며, 네트워크가 허용되는 경우 시작 시 실시간 카탈로그에서 새로고침되므로 로컬 목록이 최신 상태를 유지합니다.

🍳 레시피

아래의 모든 프롬프트는 복사하여 붙여넣기 하면 돌아갑니다.

대량 처리 레시피를 자세히. "채널 전체를 보관"하는 것은 스크립트가 아니라 도구 호출 네 개 이다:

1. list_channel_videos에 ids_only=true 사용: 페이지당 최대 500개 동영상 ID

2. 해당 ID로 submit_transcripts_job 제출(최대 4,000개, 청구 전에 중복 제거, idempotency_key를 사용하면 재시도는 무료)

3. status가 done이 될 때까지 get_transcripts_job 호출. 작업은 rate limit 안에서 스스로 속도를 조절합니다

4. get_transcripts_results를 페이지별로 가져옴. 작업이 실행되는 동안에도 계속 읽기 가능

서비스가 전달하지 못한 항목은 동영상 단위로 환불되므로, 청구 금액은 아카이브와 정확히 일치합니다.

💳 요금 및 한도

• 구독은 월 1,000~100,000 크레딧을 1,000 단위로 조절하는 슬라이더 방식이며, 1,000개당 요금은 규모가 커질수록 낮아집니다(월 10,000개는 $44.90가 아닌 $27.49). 연간 할인은 규모에 따라 약 16%에서 약 35%로 커집니다.

• 1크레딧 = 1건의 답변된 요청. YouTube에 도달하기 전에 실패한 호출(검증, rate limit, 당사 용량)은 자동으로 환불됩니다. 실시간 잔액은 X-Credits-Remaining 헤더에 표시됩니다.

• 만료되지 않는 일회성 크레딧 팩은 활성 구독 위에 추가로 구매할 수 있습니다.

• 요금 보기 · 청구 관리

🧯 호출 실패 시

• API 키가 sk_로 시작하는지 확인하세요

• 복사할 때 여분의 공백이 들어갔는지 확인하세요

• 대시보드에서 키가 활성 상태인지 확인하세요

• 해지된 키는 즉시 실패합니다. 대시보드에서 새 키를 발급하세요

• 대시보드에서 잔액을 확인하세요

• transcriptout.com/billing에서 구독하거나 크레딧 팩을 구매하세요

• 404: 요청한 언어/트랙에 동영상 자막이 없거나 ID가 잘못되었습니다. 이는 확정적인 답변이므로 재시도해도 변하지 않습니다.

• 410: 동영상이 삭제되었습니다.

• 451: 연령 제한 또는 멤버 전용 콘텐츠입니다.

• Retry-After 헤더를 준수하세요. 두 경우 모두 자동으로 환불됩니다

• 대량 작업에는 submit_transcripts_job을 사용하세요. rate limit에 충돌하는 대신 그 안에서 스스로 속도를 조절합니다

모든 오류 본문은 {"ok": false, "code": "...", "detail": "...", "request_id": "req_"} 형식입니다. 사람이 읽는 텍스트가 아닌 기계가 읽을 수 있는 code를 기준으로 분기하세요. 지원팀에 문의할 때는 request_id를 포함하세요.

🌐 일반 REST를 선호하시나요?

에이전트 대신 앱을 만들고 있나요? 동일한 백엔드가 JSON REST API로도 제공되며, 동일한 다섯 가지 트랜스크립트 형식에 원본 파일 다운로드(download=true)까지 지원합니다.

Base URL: https://api.transcriptout.com/v1

🔗 링크

• 🌐 웹사이트: transcriptout.com

• 📚 문서: transcriptout.com/docs

• 🧰 에이전트 스킬 (동일한 백엔드, MCP 불필요): github.com/artemchuikin/youtube-skills

• 💬 연락처: support@transcriptout.com

📇 MCP 레지스트리

이 서버는 공식 Model Context Protocol Registry에 다음 이름으로 게시되어 있습니다:

com.transcriptout/youtube-transcript-and-youtube-search

TranscriptOut은 독립 서비스이며, YouTube 또는 Google LLC와 제휴(aff motion), 공식,1 미 아닙니다. "YouTube"는 Google LLC의 소유 상표입니다.