YouTube MCP Server

YouTube용 Model Context Protocol (MCP) 서버 구현으로, AI 언어 모델이 표준화된 인터페이스를 통해 YouTube 콘텐츠와 상호작용할 수 있게 해줍니다.

웹사이트: zubeidhendricks.github.io/youtube-mcp-server

사용 가능한 도구

서버는 현재 10개의 MCP 도구를 제공합니다.

도구 매개변수

videos_getVideo

• videoId (string): YouTube 동영상 ID.

• parts (string[], optional): 가져올 특정 동영상 리소스 파트.

videos_searchVideos

• query (string): 검색어.

• maxResults (number, optional): 반환할 최대 결과 수.

• order (string, optional): relevance 또는 date와 같은 결과 정렬 방식.

• publishedAfter (string, optional): 이 ISO 8601 날짜 이후에 게시된 동영상만 포함합니다.

• publishedBefore (string, optional): 이 ISO 8601 날짜 이전에 게시된 동영상만 포함합니다.

• channelId (string, optional): 결과를 특정 채널로 제한합니다.

• uniqueChannels (boolean, optional): 고유 채널당 하나의 동영상만 반환합니다.

• channelMinSubscribers / channelMaxSubscribers (number, optional): 일치하는 동영상을 해당 채널의 구독자 구간으로 필터링합니다.

• channelLastUploadAfter / channelLastUploadBefore (string, optional): 일치하는 동영상을 해당 채널의 최근 업로드 활동으로 필터링합니다.

• creatorOnly (boolean, optional): 결과를 휴리스틱하게 크리에이터로 분류된 채널로 제한합니다.

• sortBy (string, optional): relevance, subscribers_asc, subscribers_desc, indie_priority, recent_activity를 지원합니다.

transcripts_getTranscript

• videoId (string): YouTube 동영상 ID.

• language (string, optional): 자막 언어 코드. YOUTUBE_TRANSCRIPT_LANG 또는 en으로 대체됩니다.

channels_getChannel

• channelId (string): YouTube 채널 ID.

응답에는 이제 다음이 포함됩니다:

• latestVideoPublishedAt

• normalizedMetadata

  • country, defaultLanguage, joinedAt, customUrl, emailsFound, contactLinks 및 크리에이터-대-브랜드 휴리스틱 필드를 포함합니다.

channels_getChannels

• channelIds (string[]): YouTube 채널 ID 목록.

• includeLatestUpload (boolean, optional): latestVideoPublishedAt 포함 여부. 기본값은 true.

channels_searchChannels

• query (string): 채널 검색어 또는 핸들.

• maxResults (number, optional): 반환할 최대 채널 수.

• order (string, optional): relevance와 같은 결과 정렬 방식.

• channelType (string, optional): 검색을 특정 채널 유형으로 제한합니다.

• minSubscribers / maxSubscribers (number, optional): 채널을 구독자 구간으로 필터링합니다.

• lastUploadAfter / lastUploadBefore (string, optional): 채널을 최근 업로드 활동으로 필터링합니다.

• creatorOnly (boolean, optional): 결과를 휴리스틱하게 크리에이터로 분류된 채널로 제한합니다.

• sortBy (string, optional): relevance, subscribers_asc, subscribers_desc, indie_priority, recent_activity를 지원합니다.

channels_findCreators

• query (string): 일치하는 동영상에서 채널을 발견하기 위한 주제, 게임 또는 언급 검색어.

• videoPublishedAfter / videoPublishedBefore (string, optional): 일치하는 동영상의 최신성 필터.

• channelMinSubscribers / channelMaxSubscribers (number, optional): 반환되는 채널의 구독자 구간 필터.

• channelLastUploadAfter / channelLastUploadBefore (string, optional): 반환되는 채널의 최근 업로드 활동 필터.

• creatorOnly (boolean, optional): 결과를 휴리스틱하게 크리에이터로 분류된 채널로 제한합니다.

• sortBy (string, optional): relevance, subscribers_asc, subscribers_desc, indie_priority, recent_activity를 지원합니다.

• sampleVideosPerChannel (number, optional): 반환되는 채널당 포함할 일치 동영상 수.

channels_listVideos

• channelId (string): YouTube 채널 ID.

• maxResults (number, optional): 반환할 최대 동영상 수.

playlists_getPlaylist

• playlistId (string): YouTube 재생목록 ID.

playlists_getPlaylistItems

• playlistId (string): YouTube 재생목록 ID.

• maxResults (number, optional): 반환할 최대 재생목록 항목 수.

Related MCP server: mcp-server-youtube

설치

Claude Desktop 빠른 설정

1. 패키지를 설치합니다:

npm install -g zubeid-youtube-mcp-server

2. Claude Desktop 구성에 추가합니다 (macOS의 경우 ~/Library/Application Support/Claude/claude_desktop_config.json, Windows의 경우 %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "zubeid-youtube-mcp-server": {
      "command": "zubeid-youtube-mcp-server",
      "env": {
        "YOUTUBE_API_KEY": "your_primary_youtube_api_key",
        "YOUTUBE_API_KEY2": "your_secondary_youtube_api_key",
        "YOUTUBE_API_KEY3": "your_tertiary_youtube_api_key"
      }
    }
  }
}

대안: NPX 사용 (설치 필요 없음)

다음을 Claude Desktop 구성에 추가합니다:

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "zubeid-youtube-mcp-server"],
      "env": {
        "YOUTUBE_API_KEY": "your_primary_youtube_api_key",
        "YOUTUBE_API_KEY2": "your_secondary_youtube_api_key",
        "YOUTUBE_API_KEY3": "your_tertiary_youtube_api_key"
      }
    }
  }
}

Smithery로 설치

Smithery를 통해 Claude Desktop용 YouTube MCP Server를 자동으로 설치하려면:

npx -y @smithery/cli install @ZubeidHendricks/youtube --client claude

구성

다음 환경 변수를 설정합니다:

• YOUTUBE_API_KEY: 기본 YouTube Data API 키

• YOUTUBE_API_KEY2: 보조 대체 API 키

• YOUTUBE_API_KEY3: 세 번째 대체 API 키

• YOUTUBE_TRANSCRIPT_LANG: 자막의 기본 언어 (선택 사항, 기본값은 'en')

YOUTUBE_API_KEY, YOUTUBE_API_KEY2, YOUTUBE_API_KEY3 중 하나 이상을 설정해야 합니다. 키의 할당량이 소진되어 요청이 실패하면 서버는 설정된 다음 키로 동일한 요청을 재시도합니다.

VS Code에서 사용

원클릭 설치를 위해 아래 설치 버튼 중 하나를 클릭합니다:

수동 설치

수동 설치를 선호하는 경우, 먼저 이 섹션 상단의 설치 버튼을 확인하세요. 그렇지 않으면 다음 단계를 따르세요:

다음 JSON 블록을 VS Code의 User Settings (JSON) 파일에 추가합니다. Ctrl + Shift + P를 누르고 Preferences: Open User Settings (JSON)을 입력하면 됩니다.

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "apiKey",
        "description": "YouTube API Key",
        "password": true
      }
    ],
    "servers": {
      "youtube": {
        "command": "npx",
        "args": ["-y", "zubeid-youtube-mcp-server"],
        "env": {
          "YOUTUBE_API_KEY": "${input:apiKey}"
        }
      }
    }
  }
}

선택적으로, 워크스페이스의 .vscode/mcp.json 파일에 추가할 수도 있습니다:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "apiKey",
      "description": "YouTube API Key",
      "password": true
    }
  ],
  "servers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "zubeid-youtube-mcp-server"],
      "env": {
        "YOUTUBE_API_KEY": "${input:apiKey}"
      }
    }
  }
}

개발

# Install dependencies
npm install

# Build
npm run build

# Start the server (requires at least one configured YouTube API key)
npm start

# Development mode with auto-rebuild
npm run dev

Docker

포함된 Docker 이미지는 기본적으로 서버를 HTTP로 시작합니다.

• 기본 전송 방식: http

• 기본 엔드포인트: http://localhost:8088/mcp

• 준비 상태 엔드포인트: http://localhost:8088/ready

• 기본 모드: 무상태

Docker 빌드는 .env를 런타임 이미지에 복사하며, 서버는 시작 시 이를 자동으로 로드합니다. 즉, docker build 중에 .env가 존재했다면 docker run 시점에 API 자격 증명을 전달하지 않고도 컨테이너를 실행할 수 있습니다.

docker build -t youtube-mcp-server .
docker run --rm -p 8088:8088 youtube-mcp-server

컨테이너의 기본값은 다음과 같습니다:

MCP_TRANSPORT=http
MCP_HOST=0.0.0.0
MCP_PORT=8088
MCP_STATELESS=true

기여

이 저장소에 기여하는 방법에 대한 자세한 내용은 CONTRIBUTING.md를 참조하세요.

라이선스

이 프로젝트는 MIT License에 따라 라이선스가 부여됩니다. 자세한 내용은 LICENSE 파일을 참조하세요.