youtube-analytics-mcp

AI 어시스턴트에게 전체 YouTube Analytics, Data v3 및 Reporting API 표면을 제공하는 MCP 서버로, 소유한 채널(여러 채널 동시 포함)을 대상으로 합니다.

대부분의 YouTube MCP 서버는 소수의 메트릭 문자열을 하드코딩하므로, 사전 설정 목록에 없는 질문은 서버를 포크하지 않고서는 답할 수 없습니다. 이 서버는 반대 방식으로 구축되었습니다: youtube_analytics_query는 reports.query가 받는 모든 매개변수를 받고, youtube_data_call / youtube_reporting_call은 다른 두 API에 대해 동일하게 작동합니다. 사전 설정은 그 위의 편의 기능일 뿐, 유일한 경로가 아닙니다.

자체 Google Cloud OAuth 클라이언트를 가져와야 합니다. 이 패키지에는 아무것도 포함되어 배포되지 않으며, 어떤 자격 증명도 제3자를 통과하지 않고, 모든 것이 stdio를 통해 로컬에서 실행됩니다.

도구

모든 데이터 도구는 선택적 account를 받으므로, 한 대화에서 두 채널을 비교할 수 있습니다.

대용량 결과는 모델을 통하지 않고 파일로

youtube_analytics_query, youtube_data_call 및 youtube_reporting_call은 outputPath(및 선택적 format: csv 또는 json, 그 외에는 확장자에서 추론)를 받습니다. 이 옵션을 사용하면 전체 결과가 디스크에 기록되고 요약(행 수, 열, 바이트 크기, 처음 세 행)만 반환됩니다. 이 옵션 없이 100행이 넘는 결과는 잘리고 해당 옵션을 가리키는 포인터가 함께 반환됩니다. 인라인으로 반환되는 1,000행 보고서는 호출자의 컨텍스트 창을 소모하고 도착했을 때 읽을 수 없기 때문입니다.

진정한 대량 작업(모든 동영상의 모든 날짜, 수개월 분량)에는 youtube_reporting_call을 통해 Reporting API를 사용하세요: reports.query가 단일 호출로 반환하지 못하는 차원 조합으로 다운로드 가능한 일별 CSV 보고서를 생성합니다.

Related MCP server: YouTube MCP Server

설정

1. Google Cloud OAuth 클라이언트, 한 번만

• 프로젝트를 만들거나 선택합니다.

• API 및 서비스 → 라이브러리: YouTube Analytics API, YouTube Data API v3 및 YouTube Reporting API를 사용 설정합니다.

• OAuth 동의 화면 → 사용자 유형: 사용자 유형을 외부로 설정합니다(내부는 Workspace 조직이 연결된 경우에만 제공됨). 동일한 사용자 유형 페이지의 테스트 사용자 아래에서 + 사용자 추가를 클릭하고 모든 채널 소유자의 Google 계정을 추가합니다 — 자신의 계정도 포함.

  이 단계를 놓치면 동의가 "…이(가) Google 확인 절차를 완료하지 않았습니다. 앱이 현재 테스트 중이며 개발자가 승인한 테스터만 액세스할 수 있습니다." 오류로 실패합니다. 프로젝트 소유자라고 해서 테스트 사용자가 되는 것은 아닙니다. 직접 자신을 추가해야 합니다.

• *게시 상태를 운영으로 설정합니다.* 이는 보기보다 중요합니다. Google:

  외부 사용자 유형과 "테스트" 게시 상태로 구성된 OAuth 동의 화면이 있는 Google Cloud Platform 프로젝트는 요청된 OAuth 범위가 이름, 이메일 주소 및 사용자 프로필의 하위 집합인 경우를 제외하고 7일 후 만료되는 리프레시 토큰이 발급됩니다.

  모든 YouTube 범위는 민감하므로 테스트 앱은 매주 재인증해야 합니다.

  게시가 단순히 스위치가 아님을 경고합니다: 콘솔은 데모 동영상을 요구하고 YouTube API 검증 검토를 거쳐야 Testing을 벗어날 수 있습니다. 개인 도구로서는 실제 작업이며, 주간 재동의가 종종 더 나은 선택입니다. 대안은 아래 7일 권한 부여 제한을 참조하세요.

• 사용자 인증 정보 → 사용자 인증 정보 만들기 → OAuth 클라이언트 ID → 데스크톱 앱. 웹 애플리케이션이 아닙니다: 이 서버는 실행할 때마다 임의의 사용 가능한 루프백 포트에서 수신하며, 웹 클라이언트는 모든 리디렉션 URI(포트 포함)를 사전에 등록해야 합니다.

• JSON을 다운로드합니다.

2. 서버에 클라이언트 위치 알리기

구성 파일에 넣습니다(config.example.json 참조):

// %APPDATA%\youtube-analytics-mcp\config.json          (Windows)
// ~/Library/Application Support/youtube-analytics-mcp/  (macOS)
// ~/.config/youtube-analytics-mcp/config.json           (Linux)
{
  "client": { "client_id": "...", "client_secret": "..." }
}

youtube-analytics-mcp --where를 실행하여 해당 디렉터리를 출력합니다. 환경 변수도 작동하며 우선합니다 — YTMCP_CLIENT_ID + YTMCP_CLIENT_SECRET, 또는 Google의 다운로드를 그대로 가리키는 YTMCP_CLIENT_FILE({"installed": …} 래퍼는 자동으로 풀립니다). YTMCP_CONFIG_DIR은 전체 디렉터리를 이동합니다.

3. 각 채널 승인

bun run auth                      # or: youtube-analytics-mcp --authorize
bun run auth -- --alias second    # name it yourself

브라우저가 동의 페이지에서 자동으로 열립니다. URL도 출력되므로 브라우저를 열 수 없는 경우(SSH, 컨테이너, CI)에 대비합니다. 채널을 소유한 Google 계정을 선택하고 승인합니다. 각 채널에 대해 반복합니다 — 브라우저에서 매번 다른 계정을 선택하세요. 계정은 --alias를 전달하지 않는 한 @handle로 이름이 지정됩니다.

YTMCP_NO_BROWSER=1을 설정하여 브라우저를 실행하지 않거나, 단일 호출에 대해 youtube_authorize 도구에 openBrowser: false를 전달합니다.

리프레시 토큰은 직접 편집하는 config.json과 분리된 동일한 디렉터리의 accounts.json에 기록되므로, 버그 보고서에 붙여넣을 수 있는 파일에는 토큰이 절대 포함되지 않습니다. 두 파일 모두 플랫폼이 지원하는 곳에서 0600 권한으로 기록됩니다.

어시스턴트도 이 작업을 수행할 수 있습니다. youtube_authorize는 동의 URL을 즉시 반환하고 백그라운드에서 계속 수신합니다. youtube_authorize_status는 종료 방식을 보고합니다. 동의는 사람이 걸리는 시간만큼 걸리고 MCP 클라이언트는 그보다 훨씬 전에 도구 호출을 포기하므로 차단하지 않습니다. URL은 대부분의 클라이언트가 서버의 stderr를 버리고 아무도 읽을 수 없는 URL은 쓸모가 없으므로 구성 디렉터리의 pending-auth.txt에도 기록됩니다.

4. MCP 클라이언트에 등록

Claude Code:

claude mcp add youtube-analytics --scope user -- bunx youtube-analytics-mcp

또는 수동으로, 모든 클라이언트의 mcpServers 맵에:

{
  "mcpServers": {
    "youtube-analytics": { "command": "bunx", "args": ["youtube-analytics-mcp"] }
  }
}

기본적으로 읽기 전용

동영상 업데이트, 댓글 게시 또는 중재, 썸네일 업로드는 라이브 채널에서 되돌릴 수 없으므로 쓰기 범위는 요청되지 않으며 비-GET 호출은 거부됩니다. 활성화하려면 YTMCP_ALLOW_WRITE=1을 설정하고 재인증해야 합니다 — 플래그만으로는 아무 효과가 없습니다. 저장된 토큰에 해당 범위가 없기 때문입니다.

동시 시청자 수, 그리고 아무도 추측하지 못하는 쿼리 형태

averageConcurrentViewers 및 peakConcurrentViewers는 종료된 스트림에서 작동하며, Studio 자체 수치와 정확히 일치합니다. API가 한 가지 형태를 제외한 모든 형태에서 거부하기 때문에 존재하지 않는 것으로 널리 알려져 있습니다: 필터가 단일 동영상을 고정해야 하고 그리고 dimensions가 livestreamPosition이어야 합니다.

어떤 오류도 누락된 차원을 지목하지 않으며, 특히 500은 요청이 잘못된 것이 아니라 메트릭이 고장난 것처럼 읽힙니다. youtube_concurrent_curve가 이를 조합하여 최고값, 평균값, 전체 분 단위 곡선을 반환합니다.

진정으로 제공할 수 없는 것

youtube_capabilities가 현재 목록을 반환합니다. 둘 다 메트릭을 요청하고 Unknown identifier를 받아 확인했으며, 이는 API가 들어본 적 없는 이름과 알고 있지만 여기서 제공할 수 없는 이름을 구분하는 방식입니다:

• 라이브 채팅 메시지 및 반응 합계. Studio 전용. liveChatMessages는 채팅을 실시간으로 읽으며 종료된 채팅을 복구할 수 없습니다.

• 노출 수 및 노출 클릭률. Studio 전용, 도달 탭에 있음.

알아두면 좋은 두 가지

"게시 이후" 기간은 없습니다. Analytics API는 순수 날짜 범위이므로 스트림 날짜를 포함하는 기간은 정의상 해당 스트림의 라이브 시청자를 반환합니다. Studio의 기본 동영상별 기간은 전체 라이브 기간을 제외하므로, 라이브 스트림을 분석할 때 쉽고 비용이 큰 함정입니다. 이 API는 그 함정에 빠질 수 없습니다.

Analytics 할당량은 별개입니다. Analytics 및 Reporting API는 Data API v3의 일일 단위 예산과 독립적으로 측정되므로, 여기서 쿼리해도 라이브 채팅 폴링이 경쟁하는 할당량을 소비하지 않습니다. 자체 콘솔 할당량 페이지가 있는 별개의 API라는 강한 추론 — 측정된 것은 아님.

개발

bun install
bun run dev          # start on stdio
bunx tsc --noEmit    # typecheck
bun run inspector    # MCP Inspector

MIT.

API는 며칠 지연됩니다

확정된 Analytics 데이터는 즉시 사용할 수 없습니다. 2026-08-25에 측정한 결과, 일별 차원 행은 08-22까지 실행되고 중단되었습니다: 이전 3일의 세션은 0행이 아니라 행을 전혀 반환하지 않았습니다. 몇 시간 전에 종료된 스트림에 대한 쿼리는 트래픽이 없는 채널처럼 보입니다.

Studio 웹 UI에는 API가 노출하지 않는 실시간 경로가 있으므로 당일 보고는 여전히 Studio에서 해야 합니다. 이 서버는 대략 3일보다 오래된 모든 것에 사용하세요. Studio를 동영상 하나씩 클릭하는 것보다 훨씬 낫습니다.

7일 권한 부여 제한, 그리고 어떤 코드로도 해결할 수 없는 이유

Cloud 프로젝트의 게시 상태가 외부 사용자 유형으로 테스트인 동안, Google은 요청된 범위가 이름, 이메일 및 프로필뿐인 경우를 제외하고 7일 후 리프레시 토큰을 취소합니다. 모든 YouTube 범위는 민감하므로 예외는 여기서 적용되지 않습니다.

이것은 자동화로 해결할 수 없습니다. 7일은 리프레시 토큰에 대한 것입니다. 새 토큰을 발급하려면 사람이 브라우저에서 동의 화면을 승인해야 합니다 — 그것이 동의의 의미이며, 우회할 간격이 아닙니다. 액세스 토큰을 더 자주 새로 고치는 것은 이와 무관합니다.

이 서버가 대신 하는 일:

• youtube_accounts는 각 권한의 ageDays를 보고하고 5일부터 경고합니다.

• 만료된 권한은 원인과 해결책을 명명하는 메시지로 실패하며, 단순한 invalid_grant가 아닙니다.

• youtube_refresh_tokens(또는 CLI에서 --refresh)는 모든 권한을 상태 점검으로 실행합니다. 이는 헤지이기도 합니다: 7일 시계가 발급 시점부터 절대적인지 사용 시 연장되는지는 확립되지 않았습니다. 연장된다면 스케줄러에서 매일 실행하면 권한을 무기한 유지합니다. 그렇지 않다면 호출 비용은 거의 없습니다. 어느 쪽이든 실행할 가치가 있습니다.

• 재동의는 youtube_authorize에 대한 한 번의 호출로, 브라우저를 직접 엽니다 — 약 15초.

실제 해결책, 비용 순서대로:

1. 게시 상태 → 프로덕션. 무료이며 권한 부여가 만료되지 않습니다. 민감한 YouTube 범위의 경우 Google은 게시를 허용하기 전에 데모 동영상과 검증 검토를 요구할 수 있으며, 개인 도구로서는 상당한 작업량입니다.

2. 내부 사용자 유형. 7일 제한도 없고 검증도 필요 없지만, 이 옵션은 프로젝트가 Google Workspace 조직 — 유료 구독 — 에 속한 경우에만 존재합니다.

3. 주간 재동의와 함께 라이브. 단일 사용자 도구의 경우 이 방법이 종종 정답입니다.