Careerly Data MCP

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

왜 이 도구인가?

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

핵심 가치

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

Quick Start

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

# 2. Claude Code 재시작 후 바로 사용
"SEO와 트래픽 상관관계 분석해줘"
"앱 웹뷰 사용자 분석해줘"
"월별 가입자 추이 보여줘"

자동 설정 기능

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

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

아키텍처

┌─────────────────────────────────────────────────────────────────┐
│                          Claude Code                             │
│              "게시물 참여율 분석해줘"                              │
│              Tool Description 기반 자동 선택                      │
└────────────────────────────┬────────────────────────────────────┘
                             │ MCP Protocol
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│              career·ly DATA MCP Server (v4.0.2)                  │
│                                                                  │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │         🎯 Orchestration Layer (커리어리 특화)               │ │
│  │  ┌──────────────┐ ┌─────────────────┐ ┌─────────────────┐  │ │
│  │  │ smart_query  │ │platform_analysis│ │unified_analysis │  │ │
│  │  │ 커리어리 특화 │ │  웹+앱 웹뷰     │ │ 5가지 분석유형  │  │ │
│  │  │  자동 인사이트│ │  트래픽 구분    │ │ 자동 퍼널/참여  │  │ │
│  │  └──────┬───────┘ └────────┬────────┘ └────────┬────────┘  │ │
│  └─────────┼──────────────────┼───────────────────┼───────────┘ │
│            │                  │                   │              │
│  ┌─────────┴──────────────────┴───────────────────┴───────────┐ │
│  │                📊 Data Sources (22 tools)                   │ │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │ │
│  │  │ GA4 Tools│  │ BQ Tools │  │ GSC Tools│  │ DB Tools │   │ │
│  │  │ (3 tools)│  │ (8 tools)│  │ (4 tools)│  │ (4 tools)│   │ │
│  │  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘   │ │
│  └───────┼──────────────┼──────────────┼──────────────┼────────┘ │
│          │              │              │              │           │
│          ▼              ▼              ▼              ▼           │
│    GA4 Data API    BigQuery API    Search Console   MySQL DB     │
│                                       API          (careerly_v2) │
│                                                                  │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │              💡 Insight Engine (커리어리 특화)               │ │
│  │   게시물 참여율 | AI검색 완료율 | 퍼널 이탈 | 플랫폼 분석     │ │
│  └────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘

기능 (22개 Tools)

🎯 Orchestration Layer (3개) - 커리어리 특화

GA4 Data API (3개)

BigQuery (8개)

Search Console (4개)

MySQL Database (4개) - v4.0 NEW

사용 예시

트래픽 분석

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

SEO 분석

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

전환 분석

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

🎯 커리어리 특화 분석 - 자동 인사이트

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

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

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

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

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

🗄️ MySQL 데이터베이스 분석 (v4.0 NEW)

"이번 달 가입자 수 보여줘"
"게시글 유형별 통계 분석해줘"
"팔로우 수 상위 100명 보여줘"
"활성 사용자 대비 게시글 작성 비율 분석해줘"
"월별 Q&A 답변 수 추이 보여줘"

MySQL 고급 쿼리

"게시글 좋아요 수 상위 50개 JOIN으로 조회해줘"
"최근 7일 가입한 사용자의 첫 게시글 작성까지 걸린 시간"
"회사별 사용자 분포 분석해줘"
"AI 채팅 세션당 평균 메시지 수 보여줘"

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

## 요약
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%)

사전 준비

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 이메일 추가 (전체)

MySQL:

• 읽기 전용 계정 준비 (SELECT 권한만 부여)
• SSH 터널 또는 직접 접속 가능한 호스트 정보

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 \
  -e MYSQL_HOST=your-host.rds.amazonaws.com \
  -e MYSQL_PORT=3306 \
  -e MYSQL_USER=analyst \
  -e MYSQL_PASSWORD=your-password \
  -e MYSQL_DATABASE=careerly_v2 \
  -- 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",
        "MYSQL_HOST": "your-host.rds.amazonaws.com",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "analyst",
        "MYSQL_PASSWORD": "your-password",
        "MYSQL_DATABASE": "careerly_v2"
      }
    }
  }
}

환경 변수

Google Cloud (GA4 / BigQuery / GSC)

MySQL Database

CLI 명령어

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

# 초기 설정 (GA4 + BigQuery + GSC + MySQL)
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:)

"MySQL 연결 실패"

• 호스트/포트가 정확한지 확인
• 사용자/비밀번호가 올바른지 확인
• 방화벽에서 해당 포트가 열려 있는지 확인
• SSL 설정 확인 (MYSQL_SSL=false로 비활성화 가능)
• npx careerly-data-mcp setup에서 "Setup MySQL only" 선택하여 재설정

"MySQL 권한 오류"

• SELECT 권한이 부여된 읽기 전용 계정인지 확인
• 올바른 데이터베이스에 접근 권한이 있는지 확인

"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@latest setup 재실행
• 수동 해결: ~/.claude/settings.json에서 환경변수가 올바르게 설정되어 있는지 확인

일반적인 문제

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

보안

• 읽기 전용: 모든 API 호출은 읽기 전용
• Service Account: 개인 계정 대신 Service Account 사용
• SQL 안전성: INSERT/UPDATE/DELETE/DROP 등 위험 쿼리 자동 차단 (BigQuery + MySQL)
• 환경 변수: 민감 정보는 환경 변수로 관리
• MySQL 보호: SELECT/WITH/SHOW/DESCRIBE/EXPLAIN만 허용, DML/DDL 완전 차단

버전 히스토리

v4.0.2 (Current)

• DB 스키마 정확성 개선 - 실제 DB 컬럼명과 Tool Description 동기화
• 테이블 관계 정보 보강 - FK 관계, snake_case/camelCase 혼용 안내 추가
• Tool Description 튜닝 - Claude 자동 도구 선택 정확도 향상

v4.0.0

• MySQL Database 통합 - 4개 신규 도구 (db_status, db_tables, db_query, db_raw_sql)
• 서비스 DB 직접 분석 - users, Posts, Follows, Questions 등 커리어리 핵심 테이블 조회
• 파라미터 기반 안전 쿼리 - WHERE/GROUP BY/집계 함수를 파라미터로 구성
• Raw SQL 지원 - JOIN, 서브쿼리, 윈도우 함수 등 복잡한 분석 (SELECT 전용)
• Setup 개선 - MySQL 개별 설정 및 통합 연결 테스트 지원
• 총 22개 도구 지원

v3.2.4

• 사이트맵 조회 도구 추가 - gsc_sitemaps (사이트맵 목록/상세 조회, 제출 상태/에러/경고 확인)
• 총 18개 도구 지원

v3.2.3

• 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가지 분석유형별 최적화 쿼리
• CLI 브랜딩 - career·ly 로고 스타일 반영
• Insight Engine - 게시물 참여율, AI검색 완료율, 퍼널 이탈 자동 계산

v3.1.0

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

v3.0.0

• Enhanced Insight Engine 추가
• Unified Analysis 도구 추가
• 자동 이상치 탐지 / 가설 생성

v2.3.0

• Search Console "Login Required" 버그 수정

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 - 자유롭게 사용하세요.