GA4 + BigQuery + Search Console 데이터 분석 MCP 서버 for Claude Code
npm install 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 기반 읽기 전용 접근
---
``bash1. 셋업 시작 (5분)
npx careerly-data-mcp@latest setup
$3
명령어가 알아서 처리합니다: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)
$3
| Tool | 설명 | 사용 예시 |
|------|------|----------|
|
| 커리어리 특화 자연어 분석 + 자동 인사이트 | "게시물 참여율 분석해줘" |
| platform_analysis | 웹 브라우저 vs 앱 웹뷰 트래픽 구분 | "앱 웹뷰 사용자 분석해줘" |
| unified_analysis | 5가지 분석유형 (performance/seo/conversion/traffic/comprehensive) | "conversion 분석해줘" |$3
| Tool | 설명 | 사용 예시 |
|------|------|----------|
|
ga4_query | GA4 데이터 조회 + 인사이트 | "채널별 전환율 분석해줘" |
| ga4_metadata | 사용 가능한 지표/차원 목록 | "GA4에서 쓸 수 있는 지표 알려줘" |
| ga4_status | 연결 상태 확인 | "GA4 연결 상태 확인해줘" |$3
| 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 연결 확인" |$3
| Tool | 설명 | 사용 예시 |
|------|------|----------|
|
gsc_query | 검색 분석 데이터 조회 | "검색어별 클릭수 상위 20개" |
| gsc_sites | 등록된 사이트 목록 | "접근 가능한 사이트 보여줘" |
| gsc_status | 연결 상태 확인 | "GSC 연결 상태" |---
사용 예시
$3
`
"지난 7일 채널별 세션수와 전환율 비교해줘"
"이번 주 vs 지난 주 트래픽 변화 분석해줘"
"모바일 vs 데스크톱 사용자 비교해줘"
$3
"검색어별 클릭수 상위 20개 보여줘"
"페이지별 평균 순위와 CTR 분석해줘"
"순위가 떨어진 페이지 찾아줘"
$3
"회원가입 퍼널 단계별 이탈률 분석해줘"
"purchase 이벤트 상세 분석해줘"
"전환율이 가장 높은 채널 찾아줘"
$3
"게시물 참여율 분석해줘"
"AI 검색 완료율 보여줘"
"질문 콘텐츠 전환율 분석해줘"
"post_impression에서 post_detail_view 전환율"
$3
"앱 웹뷰 트래픽 분석해줘"
"iOS와 Android 사용자 비교해줘"
"플랫폼별 참여도 분석해줘"
$3
"performance 분석해줘" # 일별 추이 + 참여율
"conversion 분석해줘" # 5단계 퍼널 분석
"traffic 분석해줘" # 플랫폼별 트래픽
"seo 분석해줘" # 오가닉 트래픽 품질
"comprehensive 분석해줘" # 전체 종합
$3
요약
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 주요 업데이트
$3
- 커리어리 이벤트 인식:
, question_detail_view, ai_search_start 등 자동 감지
- 자동 인사이트 생성: 게시물 참여율, AI검색 완료율, 퍼널 전환율 자동 계산
- 의도 자동 감지: SEO, 트래픽, 전환, 참여도, 플랫폼 등 9가지 의도 + 커리어리 키워드
- 교차 인사이트: 여러 소스 데이터를 통합 분석$3
| 유형 | 분석 내용 |
|------|----------|
|
performance | 일별 사용자 추이, 세션당 참여율 |
| conversion | 5단계 퍼널 (session→impression→detail→interaction→create) |
| traffic | 앱 웹뷰 vs 모바일 웹 vs 데스크톱 구분 |
| seo | 오가닉 랜딩페이지 + 검색 유입 참여도 |
| comprehensive | 핵심 이벤트 12개 종합 분석 |$3
- 웹뷰 트래픽 감지: 모바일 (direct)/(none) 패턴으로 앱 웹뷰 구분
- iOS vs Android 비교: 플랫폼별 사용자 행동 분석
- 참여도 비교: 웹 브라우저 vs 앱 웹뷰 참여도 비교
$3
- career·ly 로고: 코랄색 도트 (#E8756C) 반영
- 전문적인 UI: 배너, 상태 표시, 진행률 바 개선
---
사전 준비
$3
- Google Cloud Console에서 Service Account 생성
- JSON 키 파일 다운로드$3
- 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 이메일 추가 (전체)
$3
- Claude Code CLI 설치 필요---
수동 설정
$3
`bash
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
`$3
:`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 사용시 | GA4 속성 ID (숫자) |
| BQ_PROJECT_ID | BigQuery 사용시 | GCP 프로젝트 ID |
| BQ_LOCATION | 선택 | BigQuery 위치 (기본: US) |
| GSC_SITE_URL | GSC 사용시 | 사이트 URL |
| GOOGLE_APPLICATION_CREDENTIALS | 필수 | Service Account 키 파일 경로 |---
CLI 명령어
`bash
인터랙티브 메뉴
npx careerly-data-mcp초기 설정
npx careerly-data-mcp setup연결 테스트
npx careerly-data-mcp test-connection서버 정보
npx careerly-data-mcp infoMCP 서버 시작 (수동)
npx careerly-data-mcp serve
`> 별칭:
, careerly-ga4도 동일하게 동작합니다.---
문제 해결
$3
- GA4 Property ID가 숫자인지 확인 (analytics.google.com에서 확인)
- Service Account에 GA4 접근 권한이 있는지 확인
- GA4 Data API가 활성화되어 있는지 확인$3
- Service Account에 BigQuery Data Viewer 역할 필요
- BigQuery API가 활성화되어 있는지 확인$3
- Service Account 이메일이 Search Console에 추가되어 있는지 확인
- 사이트 URL 형식 확인 (https:// 또는 sc-domain:)$3
- Claude Code CLI가 설치되어 있는지 확인
- ~/.claude/settings.json에 수동 추가$3
1. Claude Code 완전 종료 후 재시작
2. claude mcp list로 등록 확인
3. npx careerly-data-mcp setup 재실행$3
- v3.2.2에서 수정됨: npx careerly-data-mcp@latest setup 재실행
- 수동 해결: ~/.claude/settings.json에서 careerly-ga4를 careerly-data로 변경하고 환경변수 추가$3
`bash
연결 테스트
npx careerly-data-mcp setup
"Test connections" 선택
`---
보안
- 읽기 전용: 모든 API 호출은 읽기 전용
- Service Account: 개인 계정 대신 Service Account 사용
- SQL 안전성: INSERT/UPDATE/DELETE 등 위험 쿼리 자동 차단
- 환경 변수: 민감 정보는 환경 변수로 관리
---
버전 히스토리
$3
- README 문서 개선 - 버전 히스토리 및 문제 해결 가이드 업데이트$3
- 설정 동기화 버그 수정 - 후 settings.json 자동 동기화
- Interactive Menu 개선 - 재실행 시 모든 서비스 상태 올바르게 표시
- 구버전 설정 자동 정리 - careerly-ga4 → careerly-data 마이그레이션$3
- README 아키텍처 문서 업데이트$3
- 커리어리 특화 분석 - 게시물/질문/AI검색 이벤트 자동 인식
- smart_query 개선 - 커리어리 이벤트 기반 자동 인사이트 생성
- unified_analysis 개선 - 5가지 분석유형별 최적화 쿼리
- performance: 일별 사용자 추이 + 참여율
- conversion: 5단계 퍼널 + 이탈률 분석
- traffic: 앱 웹뷰 vs 웹 브라우저 구분
- seo: 오가닉 랜딩페이지 + 참여도
- comprehensive: 핵심 이벤트 종합 분석
- CLI 브랜딩 - career·ly 로고 스타일 반영
- Insight Engine - 게시물 참여율, AI검색 완료율, 퍼널 이탈 자동 계산$3
- Smart Query Orchestrator - 자연어 → 자동 소스 선택 → 교차 인사이트
- Platform Analysis - 웹+앱 웹뷰 트래픽 구분 분석
- Tool Description 강화 - Claude 자동 도구 선택 개선
- 총 17개 도구 지원$3
- Enhanced Insight Engine 추가
- Unified Analysis 도구 추가
- 셋업 UI 개선 (ASCII 아트 배너)
- 자동 이상치 탐지 / 가설 생성$3
- Search Console "Login Required" 버그 수정
- google-auth-library 버전 고정$3
- Google Search Console 통합 (gsc_query, gsc_sites, gsc_status)$3
- BigQuery 고급 도구 추가 (bq_raw_sql, bq_event_params, bq_user_journey, bq_funnel)---
개발
`bash
npm install # 의존성 설치
npm run build # 빌드
npm run dev # 개발 모드 (watch)
npm run typecheck # 타입 체크
npm run test # 테스트 실행
``---
MIT License - 자유롭게 사용하세요.