YouTube Studio MCP

YouTube 채널의 검색 가능성을 감사하고 개선하기 위한 MCP 서버입니다.

MCP를 지원하는 모든 AI 에이전트를 내 채널의 데이터(카탈로그, Analytics API 지표, 유지율 곡선, 유입 검색어, 그리고 Studio CSV 내보내기에서만 얻을 수 있는 노출 수와 클릭률)에 연결합니다. 그런 다음 클릭률이 아닌 회수 가능한 조회수를 기준으로 무엇을 고쳐야 할지 순위를 매깁니다 — 저성과 영상의 순위 산정 방식을 참고하세요.

여덟 가지 도구: auth_status, list_videos, get_video, query_analytics, get_search_terms, get_retention_curve, import_studio_data, find_underperformers.

모든 것은 읽기 전용이며 로컬에서만 처리됩니다: SQLite 캐시, OAuth 토큰, Studio 내보내기 파일이 기기를 벗어나지 않습니다.

요구 사항

• Node.js ≥ 22

• 해당 YouTube 채널을 소유한 Google 계정

Related MCP server: MCP YouTube Intelligence

설정

1. Google Cloud 프로젝트를 만들고 API를 활성화합니다

1. https://console.cloud.google.com/로 이동하여 프로젝트를 만듭니다.

2. YouTube Data API v3와 YouTube Analytics API를 활성화합니다. (둘 다 실제로 사용됩니다: Data API는 카탈로그 동기화와 list_videos/get_video를 지원하고, Analytics API는 query_analytics, get_search_terms, get_retention_curve를 지원합니다. Google Cloud Console은 활성화한 API에 대해서만 동의 화면 범위를 추가할 수 있으므로, 다음 단계 전에 둘 다 활성화하세요.)

2. OAuth 동의 화면 구성

1. API 및 서비스 → OAuth 동의 화면으로 이동합니다.

2. 외부를 선택하고 필수 필드를 입력합니다.

3. 다음 범위를 추가합니다:

   • https://www.googleapis.com/auth/yt-analytics.readonly

   • https://www.googleapis.com/auth/youtube.readonly

   • https://www.googleapis.com/auth/youtube.force-ssl

중요 — 앱을 프로덕션으로 게시하세요. 앱이 테스트 상태인 동안 Google은 새로고침 토큰을 7일 후에 만료시키므로 매주 다시 인증해야 합니다. 앱 게시를 클릭하세요. 앱은 미검증 상태로 유지되지만 괜찮습니다: 사용자는 본인뿐이고 본인의 데이터에 접근하는 것이기 때문입니다. "미검증 앱" 경고가 한 번 표시됩니다 — 고급 → (앱 이름)으로 이동을 선택하세요.

3. OAuth 클라이언트 만들기

1. API 및 서비스 → 사용자 인증 정보 → 사용자 인증 정보 만들기 → OAuth 클라이언트 ID.

2. 애플리케이션 유형: 데스크톱 앱.

3. JSON을 다운로드합니다.

4. 설치 및 인증

npm install
npm run build

다운로드한 OAuth 클라이언트 JSON을 서버의 구성 디렉터리에 credentials.json으로 저장합니다(디렉터리가 없으면 먼저 만드세요):

# Linux/macOS — adjust the source filename to match what Google actually
# named your download (it starts with "client_secret_")
mkdir -p ~/.config/youtube-studio-mcp
mv ~/Downloads/client_secret_*.json ~/.config/youtube-studio-mcp/credentials.json

# Windows (PowerShell) — same caveat about the source filename
New-Item -ItemType Directory -Force "$env:USERPROFILE\.config\youtube-studio-mcp" | Out-Null
Move-Item "$env:USERPROFILE\Downloads\client_secret_*.json" "$env:USERPROFILE\.config\youtube-studio-mcp\credentials.json"

그런 다음 실행합니다:

node dist/index.js auth

그러면 브라우저가 자동으로 열립니다. 거기서 승인하면 토큰이 <config dir>/tokens.json에 저장됩니다. Linux/macOS에서는 파일이 소유자 전용 권한(chmod 600)으로 기록됩니다. Windows에는 이에 해당하는 파일 권한 비트가 없으므로 그 단계는 무시됩니다 — 일반적인 사용자 계정 파일 보호에 의존하세요.

브라우저가 열리지 않으면 명령이 인증 링크를 <config dir>/authorize-url.txt에도 기록합니다 — 해당 파일을 열고 링크를 클릭하세요. 터미널에서 URL을 직접 복사하지 마세요: 길이가 약 520자이고 여러 줄에 걸쳐 줄바꿈되며, 잘린 복사본은 Google에서 오해를 불러일으키는 Required parameter is missing: response_type 오류로 실패합니다(누락된 매개변수는 잘려나간 부분에 있으며, 우리가 만든 요청에 없는 것이 아닙니다).

YTMCP_HOME을 설정하면 구성 디렉터리를 재정의할 수 있습니다(예: 두 번째 채널이나 테스트 설정용). ~/.config/youtube-studio-mcp 경로 전체를 대체하므로 credentials.json, tokens.json, SQLite 캐시가 모두 함께 이동합니다.

5. AI 에이전트에 서버 등록

이 서버는 stdio를 통해 표준 MCP를 사용하므로 MCP를 지원하는 모든 클라이언트가 실행할 수 있습니다. 모든 경우에 필요한 것은 하나뿐입니다: 이 저장소의 dist/index.js에 대한 절대 경로.

대부분의 클라이언트는 동일한 JSON 형식을 공유합니다. 자신의 경로로 바꿔 넣으세요:

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

두 클라이언트는 다른 형식을 사용합니다.

VS Code / GitHub Copilot — .vscode/mcp.json, mcpServers가 아닌 servers 키 사용:

{
  "servers": {
    "youtube-studio": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/youtube-studio-mcp/dist/index.js"]
    }
  }
}

OpenAI Codex CLI — ~/.codex/config.toml, JSON이 아닌 TOML:

[mcp_servers.youtube-studio]
command = "node"
args = ["/absolute/path/to/youtube-studio-mcp/dist/index.js"]

구성 편집 후 에이전트를 다시 시작하세요. auth_status를 실행하도록 요청하면 채널 이름과 남은 할당량을 보고해야 합니다. Authenticated: NO로 보고되면 node dist/index.js auth를 다시 실행하세요.

클라이언트가 목록에 없으면 설정에서 "MCP"를 찾아보세요 — 위의 명령과 인자가 필요한 전부입니다. 구성 경로는 릴리스마다 바뀔 수 있으므로 여기 있는 경로가 존재하지 않으면 클라이언트 자체 문서를 확인하세요.

에이전트 동작에 관한 참고 사항

모든 도구는 readOnlyHint: true로 주석 처리되어 있어, 해당 힌트를 표시하는 에이전트는 쓰기 확인을 요청하지 않습니다. 이 서버는 채널을 수정하는 작업이 전혀 없습니다 — 메타데이터를 다시 쓰는 것은 이후 단계입니다.

list_videos는 동기화를 요청하지 않는 한 로컬 캐시에서 제공하며, find_underperformers와 import_studio_data는 네트워크에 전혀 접속하지 않습니다. 명시적 동기화와 Analytics 쿼리만 할당량을 소비하는데, 이는 에이전트가 탐색적으로 동작하기 때문에 중요합니다: list_videos를 스무 번 호출하는 에이전트는 비용이 들지 않지만, 카탈로그 동기화를 스무 번 하면 하루 예산을 소진할 수 있습니다. auth_status는 남은 할당량을 보고합니다.

도구

list_videos는 sync: true를 전달하지 않는 한 전적으로 로컬 SQLite 캐시에서 제공합니다 — 일반 읽기(Shorts/일반 영상, 조회수, 게시일, 제목으로 필터링하거나 정렬)는 할당량이 들지 않습니다. 아직 동기화된 것이 없으면 빈 목록을 반환하는 대신 sync: true로 다시 호출하라고 안내합니다.

get_search_terms와 get_retention_curve는 날짜 창별로 결과를 캐시합니다(할당량 참조). query_analytics는 캐시하지 않고 항상 실시간 호출을 합니다. get_search_terms는 최대 25개 행을 반환합니다 — Google이 기본 보고서를 그 수로 제한하므로, 더 넓은 날짜 범위는 반환되는 행 수가 아니라 상위 25개에 어떤 용어가 포함되는지를 바꿉니다.

할당량

YouTube는 하루 10,000유닛과 별도의 search.list 호출 100회/일을 제공합니다. 서버는 둘 다 추적하고 예비분(500유닛, 검색 호출 10회)을 보유하여 대량 작업이 대화형 도구를 사용 불가능하게 만들지 않도록 합니다. 할당량은 태평양 기준 자정에 재설정되며, auth_status가 이를 보고합니다.

전체 카탈로그 동기화(sync: true가 있는 list_videos)는 channels.list 호출 1회를 수행한 다음 업로드 재생목록을 페이지 단위로 가져오고(playlistItems.list, 페이지당 50개 동영상) 동영상 세부 정보를 배치로 가져옵니다(videos.list, 호출당 50개 ID). 각 호출은 1유닛입니다. 즉, 1 + ceil(videos/50) + ceil(videos/50)유닛 — 100개 동영상 채널의 경우 약 5유닛입니다.

YouTube Analytics API는 Cloud Console에 Data API의 10,000유닛과는 별개의 프로젝트별 할당량이 있습니다. Analytics 호출은 로컬 원장에 0유닛 비용으로 기록되므로 auth_status가 Data API 예산을 소진하는 것으로 표시하지 않습니다.

검색어 결과와 유지율 곡선은 날짜 창별로 캐시됩니다. 기본 보고서가 일별 행이 아닌 범위에 대한 순위 상위 N개를 반환하기 때문입니다. 동일한 날짜로 반복 호출하면 캐시에서 제공됩니다. 다시 쿼리하려면 refresh: true를 전달하세요.

노출 수와 CTR 가져오기

impressions와 impressionClickThroughRate는 YouTube Analytics API에 존재하지 않습니다 — Studio 전용입니다. 이를 얻으려면:

1. YouTube Studio → 분석 → 고급 모드(오른쪽 상단)

2. 노출 수 및 노출 클릭률 열이 표시되는지 확인하세요 — 내보내기에는 현재 화면에 표시된 열만 포함됩니다

3. 내보내기 → 쉼표로 구분된 값(.csv) — 세 개의 파일이 포함된 zip을 받습니다

4. 압축을 풀고 폴더 경로로 import_studio_data를 실행하세요

import_studio_data는 디스크에서 파일만 읽습니다 — YouTube Data API나 Analytics API를 호출하지 않으므로 인증이 필요 없고 API 할당량도 들지 않습니다.

날짜 창은 폴더 이름에서 읽습니다(Studio는 Contenido 2010-01-26_2026-08-09 Channel처럼 이름을 지정합니다). 재정의하려면 rangeStart와 rangeEnd 둘 다(YYYY-MM-DD)를 전달하세요 — 하나만 제공하면 폴더 이름 창으로 조용히 대체되는 대신 검증 오류로 거부됩니다. 잘못된 날짜 아래에 데이터가 경고 없이 들어갈 수 있기 때문입니다. 두 날짜 모두 실제 달력 날짜여야 하며(2026-13-45는 넘겨 넘어가지 않고 거부됨) rangeStart는 rangeEnd 이후일 수 없습니다.

노출수와 CTR은 전체 기간에 대한 집계입니다. 내보내기 파일 3개 중에서 비디오별 테이블(Datos de la tabla.csv / Table data.csv)만 노출수와 CTR을 담고 있으며, 비디오당 한 행씩 전체 날짜 범위에 걸쳐 합산된 값을 보고합니다. 내보내기 어디에도 일별 CTR은 없습니다. 일별 파일(Datos del gráfico.csv / Chart data.csv)과 채널 합계 파일(Totales.csv / Totals.csv)은 조회수만 담고 있습니다. 따라서 시간에 따른 비교는 하나의 파일을 슬라이스하는 것이 아니라, 서로 다른 범위의 내보내기 여러 개를 가져와야 합니다.

import_studio_data는 내보내기 폴더 또는 특정 CSV 경로를 모두 허용합니다. 폴더를 지정하면 테이블 파일을 자동으로 찾습니다. 나머지 두 파일 중 하나를 직접 지정하면 가져오기가 즉시 거부됩니다. CSV의 헤더는 해당 파일이 세 가지 보고서 중 어떤 것인지 명확히 알려주며(reportType은 table, chart, totals 중 하나입니다. src/studio/csvSchemas.ts 참조), 이 가져오기가 저장할 수 있는 것은 table뿐입니다. 차트 파일에는 비디오 ID가 있으므로, 단순한 가져오기는 조용히 성공하면서 노출수/CTR을 NULL로 덮어쓰고 조회수는 범위 합계 대신 마지막 날의 수치로 덮어쓸 수 있습니다. 합계 파일에는 비디오 ID가 전혀 없습니다. 두 경우 모두 아무것도 기록되기 전에 거부되며, 대신 지정해야 할 파일로 Datos de la tabla.csv / Table data.csv를 명명하는 메시지가 표시됩니다.

더 이상 공개되지 않은 비디오의 행은 저장되어 일치하지 않는 항목으로 보고됩니다. 이는 오류가 아니라 예상된 동작입니다.

Shorts

비디오가 Short로 간주되려면 180초 이하이면서 2020-09-14(Shorts가 출시된 날) 이후에 게시되어야 합니다.

기간만으로는 충분하지 않습니다. 자연스럽게 짧은 장편 비디오(뮤직비디오, 편집본, 트레일러)로 구성된 카탈로그에서 기간만으로 판단하는 규칙은 전체를 잘못 분류합니다. 2020년 이전의 휴면 채널에 대해 실시간 검증을 수행한 결과, 카탈로그의 약 70%가 Shorts로 잘못 표시되었으며 모두 오탐이었습니다. 해당 채널의 가장 최근 업로드가 Shorts 출시보다 몇 달 앞섰기 때문에 그중 어느 것도 진짜 Shorts일 수 없었습니다.

find_underperformers는 cohort 매개변수를 통해 이 플래그를 읽습니다. cohort: 'short' 또는 cohort: 'long'을 전달하면 기준선이 카탈로그의 해당 절반으로 제한되어 Shorts와 장편이 각각 같은 종류끼리만 비교됩니다. 기본값인 cohort: 'all'은 이러한 세분화를 수행하지 않고 두 집단을 하나의 혼합 기준선으로 합칩니다. 이미 하나의 코호트로만 구성된 카탈로그(이 사용자의 실제 사례처럼 전부 장편인 경우)에서는 합산이 무의미하지만, 혼합 카탈로그에서는 기본값이 서로 다른 일반적인 CTR을 가진 두 집단을 혼합합니다. 명시적으로 cohort를 전달하여 세분화하십시오. 비디오의 잘못된 플래그는 명백한 오류가 아니라 그럴듯한 잘못된 결과를 만들어내므로, 게시 날짜 가드가 중요한 이유입니다.

저조 성과 비디오의 순위 산정 방식

find_underperformers는 클릭률(CTR)이 아닌 회수 가능한 조회수로 순위를 매깁니다:

recoverable views = impressions x (baseline CTR - video CTR) / 100

이는 해당 비디오가 채널 자체의 기준선에서 얻었을 것으로 추정되는 조회수, 즉 실제로 조치를 취할 가치가 있는 수치입니다. CTR만으로 순위를 매기는 것은 세 가지 구체적인 측면에서 오해를 불러일으킵니다:

• 노출수는 집중됩니다. 채널의 대부분의 노출수는 소수의 비디오에 몰려 있으므로 "최악의 CTR"과 "가장 큰 기회"는 거의 겹치지 않는 집합입니다. 가장 낮은 비율을 가진 비디오는 종종 거의 노출되지 않은 비디오입니다.

• 노출수 0은 성과가 아니라 나눗셈으로 0% CTR을 만듭니다. 오름차순 정렬은 노출된 적이 없는 모든 비디오를 수정 목록의 맨 위에 올리는데, 이는 정확히 반대입니다.

• 채널에서 가장 높은 CTR은 대개 극히 작은 분모입니다. 우연히 전환된 소수의 노출수에 불과합니다. 그것은 승리로 포장된 노이즈입니다.

따라서 두 가지 규칙이 따릅니다. 노출수 하한선 미만의 비디오는 데이터 부족으로 보고되며 저조 성과로 순위가 매겨지지 않습니다. 그리고 기준선은 노출수 가중입니다. 가중치가 없는 평균은 트래픽이 적은 비디오가 지배하여 채널이 실제로 받는 트래픽의 거의 일부도 설명하지 못하기 때문입니다.

각 기회에는 유형이 지정됩니다. weak_metadata는 메타데이터 점수가 충분히 낮아서 먼저 수정해야 할 대상임을 의미하고, low_ctr는 메타데이터가 이미 양호하며 썸네일이나 제목의 프레이밍이 개선 여지가 있음을 의미합니다.

개발

npm test          # unit tests, no network
npm run typecheck
npm run build

npm run typecheck는 두 프로젝트를 실행합니다: tsconfig.json(src/**, 빌드)과 tsconfig.test.json(src/** + test/** + vitest.config.ts, noEmit만). 테스트 프로젝트만 실행하려면 npm run typecheck:test를 사용하십시오. Vitest 자체는 esbuild를 통해 타입만 제거할 뿐 타입 검사를 수행하지 않으므로, 테스트 파일의 타입 오류를 실제로 잡는 것은 npm run typecheck입니다.