Careerly Data MCP Server

Claude Code에서 자연어로 GA4, BigQuery, Search Console 데이터를 분석하는 MCP(Model Context Protocol) 서버입니다.

왜 MCP를 쓰나요? (vs API 직접 호출)

기존 방식의 문제점

GA4 데이터 보고 싶다 → GA4 API 문서 읽기 → 인증 설정 → 코드 작성 → 결과 해석
BigQuery 분석하고 싶다 → SQL 작성 → UNNEST 문법 검색 → 쿼리 수정 → 결과 해석

MCP 방식

"지난 7일 세션수 보여줘" → 끝!
"page_view → post_detail_view 전환율 분석해줘" → 끝!
"검색어별 클릭수 보여줘" → 끝!

핵심 장점

빠른 시작

# 1. Service Account JSON 키 파일이 있는 폴더에서 실행
cd /path/to/your/project

# 2. 설정 실행 (키 파일 자동 탐지 + Claude Code 자동 등록)
npx careerly-data-mcp setup

# 3. Claude Code 재시작 후 /mcp 확인!

자동 설정 기능

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

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

사전 준비 (관리자)

1. Google Cloud 설정

1. Google Cloud Console에서 프로젝트 생성
2. Google Analytics Data API 활성화
3. BigQuery API 활성화
4. Search Console API 활성화
5. 서비스 계정 생성 후 JSON 키 다운로드

2. GA4 권한 설정

• GA4 Admin > 속성 설정 > 속성 액세스 관리
• 서비스 계정 이메일 추가 (뷰어 권한)

3. BigQuery 권한 설정

• IAM & Admin > 서비스 계정에 BigQuery 데이터 뷰어 역할 추가

4. Search Console 권한 설정 (선택)

• Search Console > 설정 > 사용자 및 권한
• 서비스 계정 이메일 추가 (전체 권한 또는 제한된 권한)

제공 도구 (Tools)

GA4 Data API 도구

BigQuery 기본 도구

BigQuery 고급 도구 (v2.1.0)

Google Search Console 도구 (v2.2.0 신규)

사용 예시

Claude Code에서 자연어로 질문하세요:

기본 질의

"지난 7일 세션수 보여줘"
"채널별 전환수 알려줘"
"어제 대비 오늘 트래픽 어때?"
"랜딩 페이지별 이탈률 분석해줘"

고급 질의 (v2.1.0)

"page_view 이벤트에서 page_location 파라미터 추출해줘"
"사용자 ID 12345678의 행동 여정 보여줘"
"page_view → post_detail_view → post_create_start 퍼널 분석해줘"
"디바이스별 전환율 비교해줘"

Search Console 질의 (v2.2.0)

"최근 28일 검색어별 클릭수 보여줘"
"클릭률이 낮은 페이지 찾아줘"
"모바일 vs 데스크톱 검색 성과 비교해줘"
"순위가 높은데 CTR이 낮은 키워드 분석해줘"

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

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

## 인사이트
1. 전체 전환율: 2.3% (1,215명 중 28명 완료)
2. 최대 이탈 구간: page_view → post_detail_view (89.8% 이탈)
3. post_detail_view → post_create_start: 22.8% 전환 (개선 필요)

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

v2.2.0 주요 업데이트 (최신)

Google Search Console 통합

• 3개 새 도구 추가: gsc_query, gsc_status, gsc_sites
• 검색어/페이지별 클릭수, 노출수, CTR, 평균 순위 분석
• 국가별, 디바이스별 필터링 지원
• 16개월 이전 데이터까지 조회 가능

새 환경변수

GSC 권한 설정

1. Search Console > 설정 > 사용자 및 권한
2. Service Account 이메일 추가 (전체 권한 또는 제한된 권한)

v2.1.0 주요 업데이트

버그 수정

• bq_ga4_events GROUP BY 오류 해결
  • 이제 metrics 있을 때/없을 때 모두 정상 동작

새 기능

• 복합 필터 지원: filterLogic: "AND" | "OR" 옵션 추가
• Raw SQL 실행: 복잡한 쿼리도 직접 작성 가능 (SELECT만 허용)

새 도구 4개 추가

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도 동일하게 동작합니다.

문제 해결

MCP 서버가 /mcp에 안 보여요

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

PERMISSION_DENIED 에러

GA4 권한 문제:

• GA4 Admin > 속성 액세스 관리 > Service Account 이메일 추가

BigQuery 권한 문제:

• IAM & Admin > Service Account에 "BigQuery 데이터 뷰어" 역할 추가

MCP 제거

# CLI로 삭제
claude mcp remove careerly-ga4 -s user

# 또는 메뉴에서
npx careerly-data-mcp
# → Disable 선택

수동 설정 (선택)

Claude CLI로 추가

claude mcp add careerly-ga4 \
  -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.local.json:

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

보안 원칙

• bq_raw_sql은 SELECT/WITH 문만 허용 (INSERT, DELETE 등 차단)
• Service Account 키 파일은 개인 로컬에서만 관리
• 민감 데이터 접근 시 권한 최소화 원칙 적용

개발

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

라이선스

MIT