youtube-mcp

@ザビエル-zav의 YouTube 채널 분석을 Claude에서 직접 할 수 있게 하는 MCP 서버. 「지난주 동영상 중 CTR이 가장 좋았던 건?」 같은 질문에 실데이터를 가져와 답할 수 있는 상태를 목표로 한다.

Node.js 기반(Python 미사용). YouTube Analytics API / Reporting API / Data API v3를 공식 Node용 라이브러리(googleapis, google-auth-library)로 래핑하고, MCP 공식 TypeScript SDK(@modelcontextprotocol/sdk)로 도구로 공개하고 있다.

사용하는 API와 용도 구분

CTR만 획득 방식이 근본적으로 다르기(벌크 리포트) 때문에, register-reach-job.js로 작업 등록 → download-reports.js로 정기적으로 로컬에 CSV를 축적하는 별도 경로로 되어 있다.

Related MCP server: youtube-organic-mcp

설정

1. Google Cloud Console

1. 프로젝트 생성

2. 다음 3개 API 활성화

   • YouTube Analytics API

   • YouTube Reporting API

   • YouTube Data API v3

3. OAuth 동의 화면 설정(사용자 유형=외부, 테스트 사용자에 자신의 Google 계정 추가)

4. 인증 정보 > OAuth 클라이언트 ID > 앱 유형=데스크톱 앱을 만들고 JSON 다운로드

5. 다운로드한 JSON을 client_secret.json이라는 이름으로 이 리포지토리 루트에 둔다.

   client_secret.json과 최초 인증 후 생성되는 token.json은 절대 커밋하지 말 것. .gitignore에 등록되어 있지만, 실수로 git add -f 하지 않도록 주의.

2. Node.js 및 의존 패키지

Node.js 18 이상 필요(미설치 시 nodejs.org에서 LTS 버전 설치. 인스톨러에 npm도 포함되므로 Python처럼 별도 PATH 설정은 기본적으로 불필요).

npm install

3. 리치 리포트(CTR) 작업 등록 — 최우선으로 실행

Reporting API는 "작업을 등록한 날"부터 데이터 생성이 시작되며, 과거 데이터도 등록 시점부터 30일 전까지만 소급할 수 있다. 등록이 늦어질수록 과거 CTR 데이터가 유실되므로 다른 작업보다 먼저 이것만 실행해 둔다.

npm run register-reach-job

최초에는 브라우저가 열리며 인증을 요구한다(이후에는 token.json으로 자동 갱신).

4. MCP 서버 시작

npm start

Claude Desktop에서 사용하는 경우 claude_desktop_config.json에 다음과 같이 등록한다.

{
  "mcpServers": {
    "youtube-analytics": {
      "command": "node",
      "args": ["/absolute/path/to/youtube-mcp/server.js"]
    }
  }
}

5. 리치 리포트 다운로드(등록 후 몇 시간~2일 뒤)

npm run download-reports

data/reach/<report_type>/ 아래에 CSV가 축적된다. 리포트는 YouTube 측에서 60일(과거 데이터분은 30일) 후 사라지므로 정기적으로(가능하면 하루 1회) 계속 실행할 것. Windows라면 작업 스케줄러, Mac/Linux라면 cron에 등록해 두면 좋다. get_reach 도구는 이 로컬 CSV를 읽는다.

공개 도구 목록

출력은 원시 JSON이 아니라 반올림한 수치·최대 20건 정도의 텍스트 표로 반환한다(Claude 쪽 컨텍스트 소비를 줄이기 위해).

알려진 제약 사항

• Analytics API의 데이터는 YouTube Studio 표시보다 최대 2일 정도의 지연이 있다. "어제의 수치"는 가져오지 못할 수 있다.

• get_reach는 로컬에 다운로드된 CSV만 본다. download-reports.js를 실행하지 않은 기간의 데이터는 나오지 않는다.

• channel_reach_basic_a1 / channel_reach_combined_a1의 정확한 열 구성은 미확인. get_reach는 열 이름을 키워드로 추측해 읽는 폴백으로 되어 있지만, 실제로 다운로드한 CSV의 헤더로 한 번 확인할 것.

• 쓰기 계열 스코프는 붙이지 않았다(읽기 전용). 동영상을 실수로 변경·삭제하는 경로는 존재하지 않는다.

배포처 분기

스마트폰에서도 사용하고 싶다면 StdioServerTransport를 StreamableHTTPServerTransport(@modelcontextprotocol/sdk/server/streamableHttp.js)로 바꿔 기존 호스팅 환경에 함께 얹는 것이 빠르다.