Careerly Data MCP

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

왜 이 도구인가?

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

| 기존 방식 | Careerly Data MCP | |----------|-------------------| | GA4 UI에서 수동으로 리포트 탐색 | 자연어로 즉시 분석 | | BigQuery SQL 직접 작성 필요 | 대화형 쿼리 자동 생성 | | 3개 도구를 따로 열어서 확인 | 통합 분석 한 번에 | | 데이터 → 인사이트 도출 20분 | 2분 내 인사이트 제공 |

핵심 가치

• 자연어 쿼리: "지난 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.3)                  │
│                                                                  │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │         🎯 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 커리어리 특화!

| Tool | 설명 | 사용 예시 | |------|------|----------| | smart_query | 커리어리 특화 자연어 분석 + 자동 인사이트 | "게시물 참여율 분석해줘" | | platform_analysis | 웹 브라우저 vs 앱 웹뷰 트래픽 구분 | "앱 웹뷰 사용자 분석해줘" | | unified_analysis | 5가지 분석유형 (performance/seo/conversion/traffic/comprehensive) | "conversion 분석해줘" |

GA4 Data API (3개)

| Tool | 설명 | 사용 예시 | |------|------|----------| | ga4_query | GA4 데이터 조회 + 인사이트 | "채널별 전환율 분석해줘" | | ga4_metadata | 사용 가능한 지표/차원 목록 | "GA4에서 쓸 수 있는 지표 알려줘" | | ga4_status | 연결 상태 확인 | "GA4 연결 상태 확인해줘" |

BigQuery (8개)

| Tool | 설명 | 사용 예시 | |------|------|----------| | bq_query | 파라미터 기반 쿼리 | "users 테이블에서 최근 가입자 조회" | | bq_ga4_events | GA4 Export 이벤트 조회 | "purchase 이벤트 분석해줘" | | bq_raw_sql | SQL 직접 실행 | "SELECT문 실행해줘" | | bq_metadata | 데이터셋/테이블 정보 | "BigQuery 테이블 목록 보여줘" | | bq_event_params | 이벤트 파라미터 추출 | "page_view 파라미터 분석해줘" | | bq_user_journey | 사용자 여정 분석 | "사용자 행동 시퀀스 보여줘" | | bq_funnel | 퍼널 분석 | "회원가입 퍼널 이탈률 분석해줘" | | bq_status | 연결 상태 확인 | "BigQuery 연결 확인" |

Search Console (3개)

| Tool | 설명 | 사용 예시 | |------|------|----------| | gsc_query | 검색 분석 데이터 조회 | "검색어별 클릭수 상위 20개" | | gsc_sites | 등록된 사이트 목록 | "접근 가능한 사이트 보여줘" | | gsc_status | 연결 상태 확인 | "GSC 연결 상태" |

사용 예시

트래픽 분석

"지난 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가지 유형

| 유형 | 분석 내용 | |------|----------| | performance | 일별 사용자 추이, 세션당 참여율 | | conversion | 5단계 퍼널 (session→impression→detail→interaction→create) | | traffic | 앱 웹뷰 vs 모바일 웹 vs 데스크톱 구분 | | seo | 오가닉 랜딩페이지 + 검색 유입 참여도 | | comprehensive | 핵심 이벤트 12개 종합 분석 |

📱 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"
      }
    }
  }
}

환경 변수

| 변수 | 필수 | 설명 | |------|------|------| | GA4_PROPERTY_ID | GA4 사용시 | GA4 속성 ID (숫자) | | BQ_PROJECT_ID | BigQuery 사용시 | GCP 프로젝트 ID | | BQ_LOCATION | 선택 | BigQuery 위치 (기본: US) | | GSC_SITE_URL | GSC 사용시 | 사이트 URL | | GOOGLE_APPLICATION_CREDENTIALS | 필수 | Service Account 키 파일 경로 |

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 재실행

설정 후 BigQuery/GSC가 "미설정"으로 표시됨

• v3.2.2에서 수정됨: npx careerly-data-mcp@latest setup 재실행
• 수동 해결: ~/.claude/settings.json에서 careerly-ga4를 careerly-data로 변경하고 환경변수 추가

일반적인 문제

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

보안

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

버전 히스토리

v3.2.3 (Current)

• README 문서 개선 - 버전 히스토리 및 문제 해결 가이드 업데이트

v3.2.2

• 설정 동기화 버그 수정 - claude mcp add 후 settings.json 자동 동기화
• Interactive Menu 개선 - 재실행 시 모든 서비스 상태 올바르게 표시
• 구버전 설정 자동 정리 - careerly-ga4 → careerly-data 마이그레이션

v3.2.1

• README 아키텍처 문서 업데이트

v3.2.0

• 커리어리 특화 분석 - 게시물/질문/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 - 자유롭게 사용하세요.