youtube-mcp-server

Streamable HTTP를 통해 YouTube Data API v3를 도구로 노출하는 원격 MCP 서버로, claude.ai에 사용자 지정 커넥터로 추가할 수 있습니다.

의존성이 없습니다. 빌드 단계가 없습니다. node src/server.js가 전부입니다.

도구

자막은 의도적으로 포함하지 않았습니다. captions.download는 OAuth 및 동영상에 대한 편집 권한이 필요하므로, API 키로는 본인이 소유한 동영상의 자막만 가져올 수 있습니다. 비공식 스크래핑 라이브러리는 클라우드 IP 대역에서 차단된다는 보고가 널리 있으며, 바로 이 서버가 실행되는 환경입니다.

Related MCP server: mcp-server-youtube

할당량

프로젝트는 일반 버킷에서 하루 10,000유닛을 받으며, search.list는 하루 100회로 제한된 별도의 버킷에 있습니다. 이것이 도구 설계를 결정했습니다. youtube_channel_videos는 search.list?channelId= 대신 channels.list → playlistItems.list → videos.list 순서로 호출하므로, 채널을 탐색하는 데 하루 100회뿐인 검색 중 하나가 아니라 일반 유닛 3개만 사용합니다.

로컬에서 실행

cp .env.example .env        # add your YOUTUBE_API_KEY
export $(grep -v '^#' .env | xargs)
npm start

curl localhost:3000/health

curl -s localhost:3000/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | head -c 400

테스트

npm test

스텁(stub) YouTube API를 대상으로 전체 MCP 핸드셰이크, 두 전송 모드, 다섯 가지 도구와 오류 경로를 모두 실행합니다. API 키와 네트워크가 필요 없습니다.

Railway에 배포

1. 이 저장소를 GitHub에 푸시하세요.

2. Railway → New Project → Deploy from GitHub repo → 해당 저장소를 선택하세요.

3. Variables → YOUTUBE_API_KEY를 추가하세요.

4. Settings → Networking → Generate Domain.

5. https://<your-domain>/health가 "apiKeyConfigured": true를 반환하는지 확인하세요.

Railway가 PORT를 직접 설정합니다. 서버는 0.0.0.0에 바인딩하고 이를 읽습니다.

claude.ai에 추가

Customize → Connectors → Add custom connector → https://<your-domain>/mcp

OAuth 필드는 필요 없습니다. 서버는 기본적으로 인증 없이 동작합니다. 잠그려면 MCP_AUTH_TOKEN을 설정하고 커넥터의 Request 헤더에서 authorization 아래에 Bearer <token>을 넣으세요.

환경 변수

설계 노트

무상태(Stateless)입니다. 각 POST는 독립적이며, Mcp-Session-Id도 세션 맵도 없습니다. 따라서 재시작이나 두 번째 복제본이 생겨도 "No valid session ID provided"가 발생하지 않습니다.

콘텐츠 협상은 참조 SDK와 일치합니다. 클라이언트가 Accept: text/event-stream을 보내면 SSE 프레임을, 그 외에는 일반 JSON 본문을 반환합니다.

/mcp에 대한 GET과 DELETE는 405를 반환합니다. 이는 서버 시작 스트림도 닫을 세션도 없는 서버에 대해 Streamable HTTP 스펙이 기대하는 동작입니다.

Origin 헤더 검증도 DNS 리바인딩 보호도 없습니다. 이러한 방어 기능은 localhost에 바인딩된 MCP 서버를 위한 것입니다. 공개 배포에서 이를 켜 두면 Anthropic의 자체 요청도 거부하며, 이는 initialize 시간 초과의 흔한 원인입니다.

도구 실패는 JSON-RPC 오류 대신 isError: true 콘텐츠로 반환됩니다. 따라서 호출이 전송 계층에서 중단되는 대신 Claude가 무엇이 잘못되었는지 읽고 조정할 수 있습니다.

결과는 120k 문자로 잘리며, 이는 claude.ai의 약 150k 도구 결과 상한보다 낮습니다.