Careerly Data MCP

GA4, BigQuery, Search Console 데이터를 Claude Code에서 자연어로 분석

왜 이 도구인가?

데이터 분석에 드는 시간을 획기적으로 줄여줍니다.

핵심 가치

• 자연어 쿼리: "지난 7일 채널별 세션수 보여줘"처럼 말하면 됩니다
• 통합 분석: GA4 + BigQuery + Search Console 데이터를 한 번에 조회
• 자동 인사이트: 이상치 탐지, 가설 제안, 권장 조치까지 자동 생성
• 안전한 접근: Service Account 기반 읽기 전용 접근

Quick Start

# 1. 셋업 시작 (5분)
npx careerly-data-mcp@latest setup

# 2. Claude Code 재시작 후 바로 사용
"SEO와 트래픽 상관관계 분석해줘"
"앱 웹뷰 사용자 분석해줘"

자동 설정 기능

setup 명령어가 알아서 처리합니다:

1. Service Account 키 파일 자동 탐지 - 폴더에서 JSON 파일 스캔
2. GA4 + BigQuery + GSC 연결 테스트 - Property ID와 키 파일 검증
3. Claude Code MCP 자동 등록 - 재시작만 하면 바로 사용 가능

아키텍처

┌─────────────────────────────────────────────────────────────────┐
│                          Claude Code                             │
│              "게시물 참여율 분석해줘"                              │
│              Tool Description 기반 자동 선택                      │
└────────────────────────────┬────────────────────────────────────┘
                             │ MCP Protocol
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│              career·ly DATA MCP Server (v3.2)                    │
│                                                                  │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │         🎯 Orchestration Layer (v3.2 커리어리 특화)          │ │
│  │  ┌──────────────┐ ┌─────────────────┐ ┌─────────────────┐  │ │
│  │  │ smart_query  │ │platform_analysis│ │unified_analysis │  │ │
│  │  │ 커리어리 특화 │ │  웹+앱 웹뷰     │ │ 5가지 분석유형  │  │ │
│  │  │  자동 인사이트│ │  트래픽 구분    │ │ 자동 퍼널/참여  │  │ │
│  │  └──────┬───────┘ └────────┬────────┘ └────────┬────────┘  │ │
│  └─────────┼──────────────────┼───────────────────┼───────────┘ │
│            │                  │                   │              │
│  ┌─────────┴──────────────────┴───────────────────┴───────────┐ │
│  │                📊 Data Sources (14 tools)                   │ │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │ │
│  │  │  GA4 Tools  │  │  BQ Tools   │  │  GSC Tools  │         │ │
│  │  │  (3 tools)  │  │  (8 tools)  │  │  (3 tools)  │         │ │
│  │  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘         │ │
│  └─────────┼────────────────┼────────────────┼────────────────┘ │
│            │                │                │                   │
│  ┌─────────┴────────────────┴────────────────┴────────────────┐ │
│  │              💡 Insight Engine (커리어리 특화)               │ │
│  │   게시물 참여율 | AI검색 완료율 | 퍼널 이탈 | 플랫폼 분석     │ │
│  └────────────────────────────────────────────────────────────┘ │
│                                                                  │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │              📋 커리어리 이벤트 정의                         │ │
│  │  post_impression → post_detail_view → post_create_start     │ │
│  │  question_impression → question_detail_view                  │ │
│  │  ai_search_start → ai_search_complete → ai_followup_click   │ │
│  └────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘

기능 (17개 Tools)

🎯 Orchestration Layer (3개) - v3.2 커리어리 특화!

GA4 Data API (3개)

BigQuery (8개)

Search Console (3개)

사용 예시

트래픽 분석

"지난 7일 채널별 세션수와 전환율 비교해줘"
"이번 주 vs 지난 주 트래픽 변화 분석해줘"
"모바일 vs 데스크톱 사용자 비교해줘"

SEO 분석

"검색어별 클릭수 상위 20개 보여줘"
"페이지별 평균 순위와 CTR 분석해줘"
"순위가 떨어진 페이지 찾아줘"

전환 분석

"회원가입 퍼널 단계별 이탈률 분석해줘"
"purchase 이벤트 상세 분석해줘"
"전환율이 가장 높은 채널 찾아줘"

🎯 커리어리 특화 분석 (v3.2) - 자동 인사이트

"게시물 참여율 분석해줘"
"AI 검색 완료율 보여줘"
"질문 콘텐츠 전환율 분석해줘"
"post_impression에서 post_detail_view 전환율"

📱 플랫폼 분석 - 웹+앱 웹뷰

"앱 웹뷰 트래픽 분석해줘"
"iOS와 Android 사용자 비교해줘"
"플랫폼별 참여도 분석해줘"

📊 통합 분석 (5가지 유형)

"performance 분석해줘"   # 일별 추이 + 참여율
"conversion 분석해줘"    # 5단계 퍼널 분석
"traffic 분석해줘"       # 플랫폼별 트래픽
"seo 분석해줘"          # 오가닉 트래픽 품질
"comprehensive 분석해줘" # 전체 종합

실제 결과 예시 (퍼널 분석)

## 요약
page_view → post_create_start 전환율: 2.3% | 1,215 → 28명

## 인사이트
🔴 [HYPOTHESIS] "post_detail_view" 단계 병목 현상
   page_view에서 post_detail_view로 진행 시 89.8%가 이탈합니다.
   📊 근거: page_view: 1,215명, post_detail_view: 123명, 이탈률: 89.8%
   💡 권장: 해당 단계의 폼 필드, 오류 메시지, 로딩 상태를 점검하세요.

## 퍼널 시각화
1. page_view            ██████████████████████████████ 1,215명 (100%)
2. post_detail_view     ███░░░░░░░░░░░░░░░░░░░░░░░░░░░ 123명 (10.1%)
3. post_create_start    █░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 28명 (2.3%)

v3.2.0 주요 업데이트

🎯 커리어리 특화 Smart Query

• 커리어리 이벤트 인식: post_impression, question_detail_view, ai_search_start 등 자동 감지
• 자동 인사이트 생성: 게시물 참여율, AI검색 완료율, 퍼널 전환율 자동 계산
• 의도 자동 감지: SEO, 트래픽, 전환, 참여도, 플랫폼 등 9가지 의도 + 커리어리 키워드
• 교차 인사이트: 여러 소스 데이터를 통합 분석

📊 Unified Analysis 5가지 유형

📱 Platform Analysis

• 웹뷰 트래픽 감지: 모바일 (direct)/(none) 패턴으로 앱 웹뷰 구분
• iOS vs Android 비교: 플랫폼별 사용자 행동 분석
• 참여도 비교: 웹 브라우저 vs 앱 웹뷰 참여도 비교

🎨 CLI 브랜딩

• career·ly 로고: 코랄색 도트 (#E8756C) 반영
• 전문적인 UI: 배너, 상태 표시, 진행률 바 개선

사전 준비

1. Google Cloud Service Account

• Google Cloud Console에서 Service Account 생성
• JSON 키 파일 다운로드

2. API 활성화

• GA4 Data API 활성화
• BigQuery API 활성화
• Search Console API 활성화

3. 권한 설정

GA4:

• GA4 속성 > 관리 > 속성 액세스 관리 > Service Account 이메일 추가 (뷰어)

BigQuery:

• IAM에서 Service Account에 BigQuery Data Viewer 역할 부여

Search Console:

• Search Console > 설정 > 사용자 및 권한 > Service Account 이메일 추가 (전체)

4. Claude Code

• Claude Code CLI 설치 필요

수동 설정

Claude CLI로 추가

claude mcp add careerly-data \
  -s user \
  -e GA4_PROPERTY_ID=123456789 \
  -e BQ_PROJECT_ID=your-project-id \
  -e GSC_SITE_URL=https://example.com/ \
  -e GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json \
  -- npx -y careerly-data-mcp serve

설정 파일 직접 수정

~/.claude/settings.json:

{
  "mcpServers": {
    "careerly-data": {
      "command": "npx",
      "args": ["-y", "careerly-data-mcp", "serve"],
      "env": {
        "GA4_PROPERTY_ID": "123456789",
        "BQ_PROJECT_ID": "your-project-id",
        "BQ_LOCATION": "US",
        "GSC_SITE_URL": "https://example.com/",
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/key.json"
      }
    }
  }
}

환경 변수

CLI 명령어

# 인터랙티브 메뉴
npx careerly-data-mcp

# 초기 설정
npx careerly-data-mcp setup

# 연결 테스트
npx careerly-data-mcp test-connection

# 서버 정보
npx careerly-data-mcp info

# MCP 서버 시작 (수동)
npx careerly-data-mcp serve

별칭: careerly-ga4-mcp, careerly-ga4도 동일하게 동작합니다.

문제 해결

"GA4 연결 실패"

• GA4 Property ID가 숫자인지 확인 (analytics.google.com에서 확인)
• Service Account에 GA4 접근 권한이 있는지 확인
• GA4 Data API가 활성화되어 있는지 확인

"BigQuery 권한 오류"

• Service Account에 BigQuery Data Viewer 역할 필요
• BigQuery API가 활성화되어 있는지 확인

"GSC 사이트 없음"

• Service Account 이메일이 Search Console에 추가되어 있는지 확인
• 사이트 URL 형식 확인 (https:// 또는 sc-domain:)

"claude mcp add 실패"

• Claude Code CLI가 설치되어 있는지 확인
• ~/.claude/settings.json에 수동 추가

MCP 서버가 /mcp에 안 보여요

1. Claude Code 완전 종료 후 재시작
2. claude mcp list로 등록 확인
3. npx careerly-data-mcp setup 재실행

일반적인 문제

# 연결 테스트
npx careerly-data-mcp setup
# "Test connections" 선택

보안

• 읽기 전용: 모든 API 호출은 읽기 전용
• Service Account: 개인 계정 대신 Service Account 사용
• SQL 안전성: INSERT/UPDATE/DELETE 등 위험 쿼리 자동 차단
• 환경 변수: 민감 정보는 환경 변수로 관리

버전 히스토리

v3.2.0 (Current)

• 커리어리 특화 분석 - 게시물/질문/AI검색 이벤트 자동 인식
• smart_query 개선 - 커리어리 이벤트 기반 자동 인사이트 생성
• unified_analysis 개선 - 5가지 분석유형별 최적화 쿼리
  • performance: 일별 사용자 추이 + 참여율
  • conversion: 5단계 퍼널 + 이탈률 분석
  • traffic: 앱 웹뷰 vs 웹 브라우저 구분
  • seo: 오가닉 랜딩페이지 + 참여도
  • comprehensive: 핵심 이벤트 종합 분석
• CLI 브랜딩 - career·ly 로고 스타일 반영
• Insight Engine - 게시물 참여율, AI검색 완료율, 퍼널 이탈 자동 계산

v3.1.0

• Smart Query Orchestrator - 자연어 → 자동 소스 선택 → 교차 인사이트
• Platform Analysis - 웹+앱 웹뷰 트래픽 구분 분석
• Tool Description 강화 - Claude 자동 도구 선택 개선
• 총 17개 도구 지원

v3.0.0

• Enhanced Insight Engine 추가
• Unified Analysis 도구 추가
• 셋업 UI 개선 (ASCII 아트 배너)
• 자동 이상치 탐지 / 가설 생성

v2.3.0

• Search Console "Login Required" 버그 수정
• google-auth-library 버전 고정

v2.2.0

• Google Search Console 통합 (gsc_query, gsc_sites, gsc_status)

v2.1.0

• BigQuery 고급 도구 추가 (bq_raw_sql, bq_event_params, bq_user_journey, bq_funnel)

개발

npm install     # 의존성 설치
npm run build   # 빌드
npm run dev     # 개발 모드 (watch)
npm run typecheck  # 타입 체크
npm run test    # 테스트 실행

라이선스

MIT License - 자유롭게 사용하세요.