youtube-analytics-mcp

로컬에서 실행되는 읽기 전용 MCP 서버로, Claude가 YouTube 채널의 비공개 Analytics 데이터(조회수, 시청 시간, 유지율, 구독자, 트래픽 소스, 시청자 인구통계, 수익, 썸네일 노출수/CTR)에 접근할 수 있게 해줍니다. 공개 API 키만으로 이미 볼 수 있는 데이터에 그치지 않습니다.

이 서버의 어떤 기능도 채널에서 무언가를 수정, 업로드, 게시, 삭제할 수 없습니다. 전체 보안 검토는 SECURITY.md를 참조하세요.

요구 사항

• Node.js 22+

• 데이터를 가져오려는 YouTube 채널을 소유(또는 관리)하는 Google 계정

• macOS, Linux 또는 WSL(npm run auth 브라우저 흐름은 open 명령을 사용합니다)

Related MCP server: YouTube MCP Server

설정 체크리스트

다음 순서대로 진행하세요. 14단계는 Google Cloud Console에서, 58단계는 사용자 컴퓨터에서 진행합니다.

1. Google Cloud 프로젝트 만들기

console.cloud.google.com으로 이동하여 새 프로젝트를 만들거나(사용하기 편한 기존 프로젝트를 선택해도 됩니다).

2. 세 가지 API 사용 설정

프로젝트에서 APIs & Services → Library로 이동하여 다음을 각각 사용 설정합니다:

• YouTube Data API v3

• YouTube Analytics API

• YouTube Reporting API(썸네일 노출수/CTR에만 필요 — 아래 참조)

3. OAuth 동의 화면 구성

APIs & Services → OAuth consent screen으로 이동합니다.

• 사용자 유형: External(Google Workspace 계정이 있다면 Internal도 작동합니다)

• 필수 앱 이름 / 지원 이메일 필드를 입력합니다

• 메시지가 표시되면 Analytics 범위를 추가합니다(건너뛰어도 됩니다 — 앱이 직접 요청하므로 이 화면이 존재하기만 하면 됩니다)

• 앱을 운영(Production) 모드로 게시합니다. 많은 사람들이 이 단계를 건너뛰었다가 막힙니다. "Testing" 모드로 남겨둔 앱은 테스트 사용자로 명시적으로 추가한 계정으로만 로그인할 수 있으며, 또한 리프레시 토큰이 7일 후 만료되어 매주 6단계를 다시 수행해야 합니다. Google의 검증 심사를 신청하지 않고 운영 모드로 게시하는 것은 개인 도구에는 문제없습니다. 로그인 시 Google이 "unverified app" 경고를 표시하면 **Advanced → Go to [your app name] (unsafe)**를 클릭하여 진행하면 됩니다. 본인 앱에서는 예상된 동작이며 안전합니다.

4. OAuth 사용자 인증 정보 만들기

APIs & Services → Credentials → Create Credentials → OAuth client ID로 이동합니다.

• 애플리케이션 유형: Desktop app

• 이름은 아무렇게나 지정합니다

• 생성된 Client ID와 Client Secret을 복사합니다 — 5단계에서 필요합니다

여기서 리다이렉트 URI를 등록할 필요는 없습니다. 이 서버는 인증 시 임시 로컬 포트를 바인딩하며, Google은 Desktop 유형 클라이언트에 대해 모든 루프백 주소를 허용합니다.

5. 설치 및 빌드

git clone <this-repo-url>
cd youtube-analytics-mcp
npm install
npm run build

6. 사용자 인증 정보 구성

cp .env.example .env

.env를 편집하고 4단계의 Client ID / Client Secret을 붙여넣습니다:

GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret

.env는 gitignore에 포함되어 있어 커밋되지 않습니다. 선택 설정:

• GOOGLE_API_KEY — 현재 어떤 도구에도 필요하지 않습니다. 직접 서버를 확장하지 않는 한 비워 두세요.

• REVENUE_CURRENCY — 기본값은 USD입니다. 수익 수치를 해당 통화로 보고 싶다면 AdSense 지급 통화(예: BRL)로 설정하세요. Google이 서버 측에서 변환합니다.

7. 인증

npm run auth

Google 로그인을 위해 브라우저가 열리며 리프레시 토큰을 ~/.youtube-analytics-mcp/token.json에 저장합니다(사용자 본인에게만 권한이 부여되며 저장소에는 절대 포함되지 않습니다). 이 작업은 한 번만 하면 됩니다. 이후 서버가 액세스 토큰을 자동으로 갱신합니다.

작동 여부를 확인합니다:

npm run auth:status

Authenticated와 채널 이름이 표시되어야 합니다.

8. Claude Code에 연결

이 프로젝트의 dist/index.js에 대한 절대 경로를 사용하여 MCP 구성에 추가합니다:

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

Claude Code를 다시 시작하면(또는 MCP 서버를 다시 로드하면) 아래 도구들을 사용할 수 있습니다.

사용 가능한 도구

노출수 및 CTR에 대한 참고 사항

YouTube는 대화형 Analytics API(reports.query)를 통해 어떤 디멘션/필터 조합에서도 썸네일 노출수나 CTR을 제공하지 않습니다. 이는 문서에서 추측한 것이 아니라 API에서 직접 확인된 사실입니다. 해당 데이터는 YouTube의 대량 "Reach report", 즉 별도의 비동기 작업 API에만 존재합니다:

1. get_impressions_and_ctr를 처음 호출하면 Google에 정기 보고 작업을 등록합니다.

2. Google이 첫 보고서를 생성하는 데 24~48시간이 걸리며, 이후에는 대략 매일 새 보고서를 생성합니다.

3. get_impressions_and_ctr(또는 노출수/CTR 기준으로 정렬된 get_top_videos)를 호출할 때마다 새로 생성된 보고서를 ~/.youtube-analytics-mcp/reach-cache.json의 로컬 캐시에 동기화한 다음 해당 캐시에서 응답합니다.

첫 번째 보고서가 도착할 때까지 이 도구들은 impressions: 0, impressionsCtr: null과 그 이유를 설명하는 note를 반환합니다. 첫 사용 시에는 예상된 동작이며 버그가 아닙니다.

문제 해결

• npm run auth 중 "Access blocked" 오류: OAuth 동의 화면이 여전히 Testing 모드입니다. 3단계로 돌아가 계정을 테스트 사용자로 추가하거나 운영(Production) 모드로 게시하세요.

• 서버 시작 시 NotAuthenticatedError: npm run auth를 실행하세요.

• 수익이 항상 0인 경우: 채널이 수익화되지 않았거나 해당 기간의 수치가 실제로 0일 수 있습니다. 이 도구는 수익을 절대 조작하지 않습니다. 실제 권한/접근 실패인지 실제 0인지는 get_revenue_analytics의 available 필드를 확인하세요.

• get_impressions_and_ctr / 노출수 정렬 get_top_videos가 아무것도 반환하지 않는 경우: 응답의 dataCoverage를 확인하세요. earliestDate가 null이면 대량 보고 작업이 아직 첫 보고서를 생성하지 않은 것입니다(최초 호출 후 최대 48시간이 소요될 수 있습니다).

테스트

npm test

날짜/기간 검증, ISO-8601 기간 파싱, CSV 파싱, Analytics 보고서 행 매핑, 기간 비교 계산(0으로 나누는 엣지 케이스 포함)을 다루는 단위 테스트(Node 내장 테스트 러너)를 실행합니다. 이는 순수 함수 테스트일 뿐이며, 실제 Google API 호출이나 OAuth 토큰 갱신을 모킹하지 않습니다. 해당 경로는 개발 중 실제 채널을 대상으로 수동 검증되었습니다.

보안

전체 위협 모델 및 OWASP Top 10 검토는 SECURITY.md를 참조하세요. 요약: 모든 것이 읽기 전용이며, 모든 비밀 값은 저장소 외부의 사용자 컴퓨터에 보관되고, Google API 호출에 도달하는 모든 사용자 제공 값은 먼저 검증됩니다.

라이선스

MIT — LICENSE 참조.