YouTube MCP Server

호스팅되는 Model Context Protocol (MCP) 서버로, Claude, Cursor, Windsurf 및 기타 모든 MCP 클라이언트에 4개의 읽기 전용 YouTube 도구를 제공합니다. Google Cloud 프로젝트나 YouTube Data API 키 없이 YouTube를 검색하고, 동영상 및 채널 데이터를 읽고, 트랜스크립트를 가져올 수 있습니다.

https://mcp.hasdata.com/api/mcp?apis=youtube

목차

• 필요한 것

• 빠른 시작

• 예시 프롬프트

• 도구

• 오류 및 실패 경로

• 가격, 무료 티어 및 제한

• 도구 선택

• 비교

• FAQ

• HasData 링크

• 개발

• 기여

• 라이선스

Related MCP server: YouTube MCP Server

필요한 것

커스텀 헤더와 함께 streamable HTTP를 지원하는 MCP 클라이언트. 대시보드에서 무료로 만들 수 있는 HasData API 키. 그 외에는 아무것도 필요하지 않습니다. 이 서버는 원격 서버입니다. 설치할 패키지도, 실행할 컨테이너도 없으며, 어디에도 Google 계정이 필요하지 않습니다.

빠른 시작

서버 URL은 모든 클라이언트에서 동일합니다. 아래 구성은 Claude Code, Claude Desktop, Cursor, Windsurf 및 Cline에서 테스트되었습니다.

OAuth를 지원하는 클라이언트는 동일한 URL을 커넥터로 추가하고 구성 파일에 키를 넣지 않고 로그인할 수 있습니다.

claude mcp add --transport http youtube "https://mcp.hasdata.com/api/mcp?apis=youtube" \
  --header "x-api-key: your_key_here"

설정(Settings)으로 이동한 다음 커넥터(Connectors), 사용자 지정 커넥터 추가(Add custom connector)를 선택하고 https://mcp.hasdata.com/api/mcp?apis=youtube를 붙여넣은 후 로그인합니다.

구성 파일 방식으로는 claude_desktop_config.json에 다음을 추가하세요:

{
  "mcpServers": {
    "youtube": {
      "type": "http",
      "url": "https://mcp.hasdata.com/api/mcp?apis=youtube",
      "headers": { "x-api-key": "your_key_here" }
    }
  }
}

모든 프로젝트에는 ~/.cursor/mcp.json, 단일 프로젝트에는 .cursor/mcp.json:

{
  "mcpServers": {
    "youtube": {
      "url": "https://mcp.hasdata.com/api/mcp?apis=youtube",
      "headers": { "x-api-key": "your_key_here" }
    }
  }
}

~/.codeium/windsurf/mcp_config.json. Windsurf는 이 필드를 url이 아닌 serverUrl로 부릅니다:

{
  "mcpServers": {
    "youtube": {
      "serverUrl": "https://mcp.hasdata.com/api/mcp?apis=youtube",
      "headers": { "x-api-key": "your_key_here" }
    }
  }
}

{
  "mcpServers": {
    "youtube": {
      "url": "https://mcp.hasdata.com/api/mcp?apis=youtube",
      "type": "streamableHttp",
      "headers": { "x-api-key": "your_key_here" },
      "disabled": false
    }
  }
}

작업 공간의 .vscode/mcp.json:

{
  "servers": {
    "youtube": {
      "type": "http",
      "url": "https://mcp.hasdata.com/api/mcp?apis=youtube",
      "headers": { "x-api-key": "your_key_here" }
    }
  }
}

~/.codex/config.toml:

[mcp_servers.youtube]
url = "https://mcp.hasdata.com/api/mcp?apis=youtube"

[mcp_servers.youtube.headers]
"x-api-key" = "your_key_here"

~/.gemini/settings.json:

{
  "mcpServers": {
    "youtube": {
      "httpUrl": "https://mcp.hasdata.com/api/mcp?apis=youtube",
      "headers": { "x-api-key": "your_key_here" }
    }
  }
}

예시 프롬프트

코드가 아닌 프롬프트입니다. 하나를 붙여넣으면 에이전트가 도구를 스스로 선택합니다. 각 프롬프트에는 필요한 호출 수가 표시되어 있습니다. MCP에서는 모델이 호출 횟수를 결정하고, 성공적인 호출마다 10크레딧이 소모되기 때문입니다.

지난 한 달간 Model Context Protocol에 관한 가장 많이 조회된 동영상 10개를 찾은 다음, 가장 상위 동영상의 트랜스크립트를 가져와서 도구 호출에 대해 주장하는 세 가지를 알려주세요.

호출 2회, 20크레딧.

@GoogleDevelopers 채널을 가져오세요. 이 채널이 게시하는 탭을 나열한 다음, 마지막 업로드 5개를 요약하고 반복되는 주제를 알려주세요.

호출 2회, 20크레딧. 아직 보지 않은 탭을 읽으려면 두 번째 호출이 필요합니다. 탭 목록이 첫 번째 응답 안에 포함되어 오기 때문입니다.

이 동영상 ID dQw4w9WgXcQ를 가져오세요. 통계를 확인한 다음, 관련 동영상 중 같은 채널에서 온 것이 무엇인지 확인하세요.

호출 1회, 10크레딧. 관련 동영상은 같은 응답에 포함되어 옵니다.

YouTube에서 "web scraping tutorial"을 검색하되, 업로드 날짜순으로 정렬하고 4분 미만 동영상만 필터링한 다음, 각 결과에 챕터 제목이 있으면 알려주세요.

호출 1회, 10크레딧.

이 동영상에 독일어 트랜스크립트가 있으면 가져오고, 어떤 언어로 제공되는지 알려주세요.

호출 1회, 10크레딧.

검색은 YouTube 자체 필터 토큰을 사용하며, 에이전트는 후처리 없이 길이, 업로드 날짜, 콘텐츠 유형으로 범위를 좁힙니다. 트랜스크립트는 사용 가능한 언어 트랙 목록과 함께 제공되므로 에이전트는 추측하지 않고 언어를 선택할 수 있습니다.

페이지네이션은 호출할 때마다 비용이 발생합니다. 검색 후 페이지를 두 번 넘기고 트랜스크립트 3개를 가져오는 연구 프롬프트는 호출 6회, 60크레딧입니다. 무료 체험은 개방형 크롤링보다 좁은 질문에서 더 오래 사용할 수 있습니다.

도구

4개의 도구, 모두 읽기 전용입니다. 아래 샘플은 실제 호출에서 축약된 것이며, 숫자는 YouTube 업데이트에 따라 변합니다. 형태로 읽어주세요. 각 도구 이름은 전체 필드 목록을 담은 엔드포인트 참조 문서로 연결됩니다.

샘플은 페이로드이지 전체 응답이 아닙니다. tools/call 결과는 하나의 텍스트 블록을 담고 있으며, 그 텍스트는 url, status, text, json을 포함하는 JSON이고, 스크랩된 데이터는 json 아래에 있습니다. 원시 JSON-RPC 응답에서 경로는 result.content[0].text를 파싱한 다음 .json입니다. 채팅 클라이언트는 이를 자동으로 풀어주지만, 엔드포인트에 직접 통신하는 코드는 그렇지 않습니다.

YouTube 검색 결과 가져오기

hasdata_youtube_search_getYoutubeSearchResults

YouTube를 검색하고 결과 유형별로 나뉜 전체 결과 페이지를 반환합니다.

결과 페이지는 videoResults, shortsResults, inlineShortsResults, playlistResults, channelResults, shelves로 나뉘며, 유료 배치는 adsResults와 sponsoredResults에 있습니다. 어떤 블록이 나타날지는 쿼리에 따라 달라지며, 보고할 내용이 없는 블록은 빈 배열이 아니라 아예 없습니다. 반복하기 전에 키가 있는지 확인하세요. searchInformation은 총계를 담고, pagination.nextPageToken은 paginationToken으로 다시 전달하는 값입니다. 광고는 유기적 배열에 섞이지 않지만, 건너뛰어야 할 광고 배열이 두 개 있습니다.

{
  "positionOnPage": 1,
  "videoId": "GuTcle5edjk",
  "title": "you need to learn MCP RIGHT NOW!! (Model Context Protocol)",
  "viewsOriginal": "1.6M views",
  "views": 1653824,
  "length": "38:40",
  "publishedDate": "11 months ago",
  "extensions": ["4K"],
  "chapters": [
    { "title": "Intro", "time": "0:00" },
    { "title": "Problem: LLMs Suck at Accessing Code", "time": "0:40" }
  ],
  "channel": { "name": "NetworkChuck", "verified": true }
}

여기서 언급할 만한 것이 두 가지 있습니다. views는 1.6M views 표시 문자열 옆의 파싱된 정수이므로 접미사 파서가 필요 없습니다. 그리고 chapters는 동영상 자체뿐 아니라 검색 결과 안에도 함께 반환되지만, 일부 동영상에만 있습니다.

검색 엔드포인트 참조는 엔드포인트가 허용하는 모든 sp 및 filters__ 토큰을 나열합니다.

YouTube 동영상 데이터 가져오기

hasdata_youtube_video_getYoutubeVideo

ID로 동영상 하나를 가져옵니다.

title, thumbnail, channel, publishedDate, lengthSeconds, category, isFamilySafe, isUnlisted와 함께 relatedVideos, endScreenVideos, keywords, captions, music, socialLinks 배열을 반환합니다. description은 content에 전체 텍스트를 담고, 모든 링크와 해시태그가 startIndex, length, text, url을 갖는 links 배열을 포함하는 객체입니다. text 필드는 작성자가 쓴 그대로의 링크를, url은 YouTube의 리디렉션 래퍼를 담습니다. 설명에서 스폰서나 제휴사 대상을 추출할 때 중요합니다.

아래 샘플을 복사하기 전에 도구별로 파싱된 필드 이름을 읽어두세요. 검색 및 채널 결과는 파싱된 숫자를 views에, 표시 문자열을 viewsOriginal에 넣습니다. 이 응답은 그 반대로, 문자열을 views에, 숫자를 extractedViews에 유지하며, likes와 subscribers에도 동일한 반전이 적용됩니다. 잘못 사용하면 item.views > 100000이 여기서 문자열을 비교하며 예외를 던지지 않습니다.

{
  "title": "Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)",
  "views": "1,806,075,152 views",
  "extractedViews": 1806075152,
  "likes": "19M",
  "extractedLikes": 19344370,
  "publishedDate": "Oct 24, 2009",
  "lengthSeconds": 214,
  "category": "Music",
  "channel": { "name": "Rick Astley", "subscribers": "4.53M subscribers", "extractedSubscribers": 4530000 }
}

YouTube 채널 데이터 가져오기

hasdata_youtube_channel_getYoutubeChannel

ID 또는 핸들로 채널을 가져오며, 한 번에 하나의 탭을 가져옵니다.

기본 탭에서는 channelInfo, featuredVideo, sections를 반환합니다. 다른 탭은 각자 다른 형태를 반환합니다. channelInfo에는 핸들, 아바타, 배너, 설명, 채널 키워드, 채널의 rssUrl이 포함되어 있어, 폴링 없이도 채널을 계속 시청할 수 있습니다.

아래 샘플의 availableTabs 배열에는 표시용 라벨이 들어 있으며, tab이 받아들이는 값과는 다릅니다. Home, Live, Courses, Search는 어떤 매개변수 값에도 매핑되지 않으며, 나머지는 소문자로 바꿔야 합니다. 목록을 읽고 각 항목을 그대로 전달하는 에이전트는 첫 번째 항목에서 실패합니다.

{
  "channelInfo": {
    "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "name": "Google for Developers",
    "handle": "@GoogleDevelopers",
    "rssUrl": "https://www.youtube.com/feeds/videos.xml?channel_id=UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "isFamilySafe": true,
    "availableTabs": ["Home", "Videos", "Shorts", "Live", "Courses", "Playlists", "Posts", "Search"]
  }
}

YouTube 동영상 자막 가져오기

hasdata_youtube_transcript_getYoutubeTranscript

동영상의 타임스탬프 자막입니다.

응답의 selected를 신뢰하기 전에 확인하세요. 동영상에 없는 languageCode를 요청해도 실패하거나 빈 값을 반환하지 않고, 조용히 기본 트랙으로 대체됩니다. 목록의 각 항목에는 languageName과 languageCode가 있으며, 같은 언어가 두 번 나타날 수 있습니다. 한 번은 사람이 작성한 트랙, 한 번은 type이 asr인 트랙입니다.

{
  "transcript": [
    { "startMs": 320, "endMs": 18800, "snippet": "[Music]", "startTimeText": "0:00" },
    { "startMs": 18800, "endMs": 21800, "snippet": "We're no strangers to", "startTimeText": "0:18" }
  ],
  "availableTranscripts": [
    { "languageName": "English", "languageCode": "en" },
    { "languageName": "English", "languageCode": "en", "type": "asr", "selected": true },
    { "languageName": "German (Germany)", "languageCode": "de-DE" },
    { "languageName": "Japanese", "languageCode": "ja" }
  ]
}

오류 및 실패 경로

클라이언트가 도구 호출에서 HTTP 오류 코드를 보는 경우는 거의 없습니다. MCP 계층이 200으로 응답하고 실패를 결과 안에 넣으며, isError를 true로 설정하고 사유를 텍스트로 담습니다. 에이전트는 상태 줄을 기대하는 자리에서 메시지를 읽게 됩니다.

잘못된 키는 연결 실패가 아닌 도구 출력으로 드러납니다. tools/list는 비어 있지 않은 키를 모두 받아들이고 네 개의 도구를 모두 반환하므로, 클라이언트는 핸드셰이크를 완료하고 정상으로 표시됩니다. 이후 첫 번째 도구 호출에서 isError: true와 텍스트 HasData API error: 401 Unauthorized가 반환됩니다. 그 문자열을 주의하세요. 그 이전에는 흐름 어디에서도 문제를 보고하지 않기 때문입니다.

키 누락은 유일한 실제 HTTP 오류입니다. 인증은 모든 도구 실행 전에 이루어지며, 연결 자체가 401로 실패합니다. CORS 헤더는 존재하므로 브라우저 클라이언트는 불투명한 네트워크 오류 대신 상태 코드를 읽을 수 있습니다.

도구 스키마를 위반하는 인자는 스크레이핑이 시작되기 전에 거부됩니다. 서버는 isError: true와 텍스트 MCP error -32602: Input validation error로 응답하며, 문제가 되는 필드를 지목합니다. 아무것도 가져오지 않고 과금도 발생하지 않습니다. 메시지는 필드 이름을 알려주지만 허용되는 값은 알려주지 않으므로, 위의 매개변수 표가 기준이 됩니다.

호출이 성공했는데 결과가 없는 경우가 사람들을 가장 자주 당황시킵니다. 일반적인 결과로 도착하며 requestMetadata.status는 ok이고 data 키만 없습니다. 본문 어디에도 결과가 비어 있다는 표시가 없습니다. 오류를 테스트하지 말고 필요한 필드를 테스트하세요.

플랫폼이 ID를 거부하면 400을 반환합니다. requestMetadata.status는 error로 설정됩니다. 존재하지 않는 채널 핸들이 일반적인 원인입니다.

데이터가 포함된 결과에는 requestMetadata.id도 함께 오므로 지원 문의 시 이 ID를 인용하세요.

요금, 무료 체험 한도 및 제한

모든 YouTube 도구는 성공적인 호출당 10크레딧이 소요됩니다. 응답 크기에 따라 요금이 달라지지 않습니다. 검색 결과가 한 페이지든 동영상 하나뿐이든 가격은 같습니다.

무료 체험은 카드 등록 없이 30일간 1,000크레딧이며, YouTube 호출 100회에 해당합니다. 이후에는 활성 계정에 잔액이 100크레딧 미만으로 떨어질 때마다 매일 100크레딧이 자동 충전됩니다. 사용량이 적은 에이전트는 무료 체험 한도 안에서 무기한 실행될 수 있습니다.

유료 요금제는 월 49달러부터 시작하며 200,000크레딧, 즉 20,000회 호출에 해당합니다. 크레딧 단가는 사용량이 많을수록 낮아집니다. 1,000크레딧당 2.45달러에서 시작해 엔트리 요금제는 0.99달러, Business는 0.83달러, Growth는 0.75달러까지 내려갑니다. 가장 큰 대용량 요금제는 월 499달러에 700,000크레딧을 제공합니다.

요금제는 동시 요청 수(concurrency)도 결정합니다. 무료 체험은 동시에 1개의 요청만 허용하며, Startup은 15개, Business는 30개, Growth는 50개입니다. 대용량 요금제는 200개에서 1,500개까지 지원합니다. 여러 도구 호출을 동시에 실행하는 에이전트는 동시 요청 한도에 먼저 도달할 수 있으므로, 방어적으로 처리하세요.

HTTP 200이 아닌 응답은 과금되지 않습니다. 성공했지만 결과가 없는 호출도 여전히 호출로 간주되어 과금됩니다.

도구 선택

apis 쿼리 매개변수가 에이전트가 볼 도구를 결정합니다. 도구가 적을수록 모델이 도구 정의에 사용하는 컨텍스트가 줄어들고, 잘못된 도구를 고를 가능성도 줄어듭니다.

?apis=youtube                    the four tools in this repo
?apis=youtube,google_serp        add Google search
?apis=youtube,tiktok,instagram   a social research bundle

이 매개변수는 youtube 같은 공급자 이름과 google_maps_search 같은 개별 API 이름을 받습니다. 철자가 틀린 이름은 무시됩니다. 모든 이름이 틀리면 요청은 400으로 실패하고, 본문에는 인식하지 못한 이름과 유효한 모든 값이 함께 나열됩니다. 매개변수를 생략하면 동일한 엔드포인트가 57개 도구를 모두 노출합니다.

공식 YouTube Data API v3와의 비교

마지막 두 항목이 중요합니다. 일일 할당량이 사용량을 충당하고 자신이 소유한 채널만 조회한다면 공식 API가 더 저렴한 선택입니다.

대부분의 다른 YouTube MCP 서버는 자막만 제공합니다. 이 서버는 검색, 조회수·좋아요를 포함한 동영상 읽기, 채널 탭 탐색까지 지원하므로, 에이전트는 두 번째 서버 없이도 전체 리서치 과정을 한 번에 처리할 수 있습니다.

이 서버가 하지 않는 일. 댓글 없음, 채널 관리 없음, 업로드 없음, 분석 없음, 비공개 데이터 없음. 로그아웃한 방문자가 볼 수 있는 것만 읽습니다.

FAQ

공식 YouTube MCP 서버가 있나요?

Google은 공식 서버를 제공하지 않습니다. YouTube에는 퍼스트파티 MCP 서버가 없습니다. 모든 옵션은 제3자가 YouTube Data API v3 또는 공개 페이지를 기반으로 직접 구축한 것입니다. 이 서버는 HasData가 유지관리하며 공개 페이지를 읽기 때문에 Google 자격 증명이 필요하지 않습니다.

YouTube MCP 서버란 무엇인가요?

YouTube 데이터를 AI 클라이언트가 호출할 수 있는 도구로 노출하는 서버입니다. 클라이언트는 Model Context Protocol을 통해 도구 호출을 보내고, 서버는 데이터를 가져와 구조화된 JSON으로 반환하며, 모델은 결과를 사용하고 HTML 페이지를 직접 보지 않습니다. 이 서버는 네 개의 도구를 노출하며 원격으로 실행됩니다. 클라이언트는 URL에 연결할 뿐 로컬 프로세스를 시작하지 않습니다.

YouTube API 키나 Google Cloud 프로젝트가 필요한가요?

아니요. 유일한 자격 증명은 HasData 키입니다. 만들 Google Cloud 프로젝트도, 작성할 할당량 양식도, OAuth 동의 화면도 없습니다. 도구가 공개 YouTube 페이지를 읽지 YouTube Data API를 호출하지 않기 때문입니다.

호스팅이나 실행 환경이 필요한가요?

아니요. 이 서버는 streamable HTTP 기반의 원격 MCP 서버입니다. 설치할 것도, 유지할 컨테이너도, 재시작할 프로세스도 없습니다.

데이터는 실시간인가요, 캐시된 것인가요?

실시간입니다. 각 호출은 요청 시점에 페이지를 가져오며 고유한 requestMetadata.id를 갖습니다. 동일한 두 호출은 저장된 복사본의 재생이 아니라 두 번의 별도 가져오기입니다. 조회수, 좋아요 같은 카운터는 페이지를 추적하므로 페이지가 변하면 함께 움직입니다.

YouTube가 레이아웃을 바꾸면 어떻게 되나요?

사용자 측에서는 아무 일도 일어나지 않습니다. 저희가 변경 사항을 추적하고 응답 스키마를 안정적으로 유지하므로 필드 이름과 유형은 그대로입니다. 값이 없는 필드는 null로 존재하지 않고 항목에서 아예 빠집니다. 선택 필드는 기본값과 함께 읽으세요.

다른 HasData API와 함께 사용할 수 있나요?

네. apis 매개변수는 목록을 받으며, ?apis=youtube,google_serp를 사용하면 에이전트에게 YouTube 도구 네 개와 Google 검색 도구가 함께 제공됩니다. 매개변수를 생략하면 모든 도구를 사용할 수 있습니다.

모든 동영상의 자막을 얻을 수 있나요?

동영상에 자막이 있는 경우에만 가능하며, availableTranscripts가 요청 전에 어떤 자막이 존재하는지 알려줍니다.

키를 붙여넣는 대신 OAuth로 로그인할 수 있나요?

네, OAuth를 지원하는 클라이언트에서는 가능합니다. Claude Desktop과 Cursor는 엔드포인트를 커넥터로 추가하고 로그인할 수 있습니다. 무인 에이전트와 스크립트는 x-api-key 헤더를 사용합니다.

규정 준수 및 개인 데이터

HasData는 공개적으로 이용 가능한 데이터에만 접근합니다. 플랫폼의 이용약관이 자동화된 접근을 제한할 수 있으며, 규정 준수에 대한 책임은 사용자 본인에게 있습니다. 수집하는 데이터에 개인 정보가 포함된 경우, GDPR, CCPA 또는 해당 관할권의 동등한 규정에 따른 적법한 근거가 있는지 확인하십시오.

HasData 링크

개발

이 저장소는 원격 서버에 대한 구성 및 문서입니다. 빌드 단계나 컨테이너화할 항목이 없습니다.

test/ 디렉터리의 테스트는 도구 계약(tool contract), 즉 이 저장소에 커밋 없이도 깨질 수 있는 부분을 검증합니다. 테스트는 ?apis=youtube가 정확히 네 개의 도구를 반환하는지, 모든 도구가 필수 매개변수를 여전히 선언하는지, 이름이 변경되지 않았는지, 사용 중인 키가 실제로 승인되는지 확인합니다. 마지막 검사는 실제로 도구를 호출하며 10크레딧이 소요되는데, 이는 올바른 이유로 실패할 수 있는 카나리(canary)의 비용입니다.

# macOS and Linux
HASDATA_API_KEY=your_key_here npm test

# Windows PowerShell
$env:HASDATA_API_KEY="your_key_here"; npm test

동일한 테스트 스위트가 모든 푸시 시 CI에서 실행되고, 주 1회 예약 실행됩니다. 업스트림 도구 목록은 이 저장소를 건드리지 않고도 변경될 수 있기 때문입니다. 실패는 도구 목록이 변경되었거나, 키가 작동을 멈췄거나, 엔드포인트에 연결할 수 없음을 의미하며, 단언(assertion) 메시지에 원인이 명시됩니다.

기여

도구 테이블과 응답 샘플의 수정이 가장 유용한 기여입니다. 이 부분들이 실제 데이터와 어긋나기 쉽기 때문입니다. 수행한 호출과 받은 응답을 포함해 주십시오. 포크에서 온 풀 리퀘스트는 키 없이 테스트 스위트를 실행하며, 실시간 검사는 빨간불 대신 건너뜁니다.

라이선스

MIT. LICENSE 참조.