YouTube MCP Connector for Claude.ai

Claude.ai가 HTTPS를 통해 읽기 전용 YouTube 도구를 사용할 수 있게 해주는 프로덕션 원격 MCP 서버:

• search_videos

• get_trending_videos

• get_channel_videos

• get_video_details

• get_engagement_stats

• get_transcript

• search_transcript

이 서비스는 검색, 메타데이터, 트렌딩 및 채널 업로드에 공식 YouTube Data API v3를 사용합니다. 트랜스크립트 가져오기는 최선 노력(best-effort) 방식입니다. 먼저 공개 InnerTube 캡션 트랙을 시도한 다음 YouTube 시청 페이지 캡션 검색을 시도합니다. 이 서비스는 CAPTCHA, 차단 또는 속도 제한을 우회하지 않습니다.

로컬 설정

npm install
cp .env.example .env

최소한 다음을 설정하세요:

YOUTUBE_API_KEY=your_google_api_key
AUTH_MODE=none

로컬에서 실행:

npm run dev

헬스 체크:

curl http://localhost:3000/health
curl http://localhost:3000/ready

빌드 및 테스트:

npm test
npm run build

Related MCP server: youtube-research

프로덕션 환경

최소 Railway 테스트 변수:

YOUTUBE_API_KEY=...
AUTH_MODE=none

Redis가 권장되지만, 앱은 Redis 없이도 시작할 수 있으며 프로세스 내 no-op 캐시를 사용합니다.

전체 프로덕션 변수:

NODE_ENV=production
YOUTUBE_API_KEY=...
AUTH_MODE=oauth
AUTH_ISSUER=https://YOUR_AUTH0_DOMAIN/
AUTH_AUDIENCE=https://youtube-claude-mcp
AUTH_JWKS_URL=https://YOUR_AUTH0_DOMAIN/.well-known/jwks.json
AUTH_REQUIRED_SCOPE=youtube:read
REDIS_URL=...

기본 캐시 TTL:

TRANSCRIPT_CACHE_TTL_SECONDS=604800
VIDEO_DETAILS_CACHE_TTL_SECONDS=900
TRENDING_CACHE_TTL_SECONDS=600
CHANNEL_VIDEOS_CACHE_TTL_SECONDS=600

Auth0 설정

1. Auth0 API를 생성하거나 재사용합니다.

2. API 식별자를 AUTH_AUDIENCE와 동일한 값으로 설정합니다.

3. youtube:read 스코프를 추가합니다.

4. Auth0 발급자 URL을 AUTH_ISSUER로 사용합니다.

5. 테넌트 JWKS 엔드포인트를 AUTH_JWKS_URL로 사용합니다.

6. 적절한 Auth0 클라이언트 정보로 Claude.ai 사용자 지정 커넥터 OAuth 고급 설정을 구성합니다.

/mcp 엔드포인트는 AUTH_MODE=oauth일 때 유효한 Authorization: Bearer <token>이 필요합니다.

Railway 배포

1. 저장소를 GitHub에 푸시합니다.

2. GitHub 저장소에서 Railway 프로젝트를 생성합니다.

3. Railway는 railway.json을 통해 커밋된 Dockerfile을 사용해야 합니다.

4. 서비스 변수를 추가합니다:

YOUTUBE_API_KEY=...
AUTH_MODE=none

5. 배포하고 /health를 엽니다.

6. 공유 캐싱을 원한다면 나중에 Railway Redis를 추가한 다음 REDIS_URL을 설정합니다.

7. AUTH_MODE=oauth 및 Auth0 변수를 설정하여 Auth0로 전환합니다.

Render 배포

1. Render Redis 인스턴스를 생성합니다.

2. 이 저장소에서 Render Web Service를 생성합니다.

3. Docker 배포를 선택합니다.

4. 프로덕션 환경 변수를 추가합니다.

5. 배포합니다.

6. 확인합니다:

curl https://YOUR_RENDER_URL/health
curl https://YOUR_RENDER_URL/ready
curl -i https://YOUR_RENDER_URL/mcp

인증되지 않은 /mcp는 401을 반환해야 합니다.

Claude.ai 커넥터

1. Claude.ai 설정을 엽니다.

2. Customize로 이동한 다음 Connectors를 선택합니다.

3. 사용자 지정 커넥터를 추가합니다.

4. 다음을 사용합니다:

https://YOUR_RENDER_URL/mcp

5. 프로덕션 인증이 활성화된 경우 OAuth 고급 설정을 구성합니다.

6. 채팅에서 커넥터를 활성화합니다.

데모 프롬프트:

• YouTube에서 최근 MCP 서버 튜토리얼 5개를 검색합니다.

• 지금 파키스탄에서 가장 인기 있는 동영상은 무엇인가요?

• @GoogleDevelopers의 최신 동영상을 보여줍니다.

• 이 YouTube URL의 조회수, 좋아요 수 및 길이를 가져옵니다.

• 이 동영상의 참여율을 계산합니다.

• 트랜스크립트를 가져와 요약합니다.

• 트랜스크립트에서 인증을 언급하는 부분은 어디인가요?

운영 참고 사항

• 가능하면 Google Cloud에서 YouTube API 키를 제한하고 교체합니다.

• API 키, bearer 토큰 또는 전체 인증 헤더를 로그에 기록하지 마세요.

• 검색 호출은 할당량을 많이 소모합니다. 가능하면 채널 업로드와 캐시된 메타데이터를 우선적으로 사용하세요.

• Redis 장애는 캐시 동작을 저하시키지만 일반 도구 호출을 실패시키지는 않습니다.

• 캡션이 비활성화되거나, 제공되지 않거나, 지역 제한이 있거나, YouTube에 의해 차단된 경우 트랜스크립트 가져오기가 실패할 수 있습니다.

• CAPTCHA 또는 봇 차단 응답은 오류로 표시됩니다. 이 서비스는 우회를 시도하지 않습니다.

문제 해결

• YOUTUBE_API_KEY is required 오류로 시작이 실패하는 경우: 서버 측 API 키를 설정하세요.

• 프로덕션에서 REDIS_URL is required 오류로 시작이 실패하는 경우: Render Redis를 연결하고 해당 URL을 설정하세요.

• /mcp가 401을 반환하는 경우: 토큰이 없거나, 만료되었거나, 형식이 잘못되었거나, 잘못된 발급자가 서명한 것입니다.

• /mcp가 403을 반환하는 경우: 토큰은 유효하지만 youtube:read 스코프가 없습니다.

• 트랜스크립트 도구가 사용 불가를 반환하는 경우: 동영상에 공개 캡션이 없을 수 있습니다.

• YouTube 할당량 초과: 할당량 재설정을 기다리거나, 할당량 증가를 요청하거나, 검색 사용량을 줄이세요.