Careerly GA4 MCP Server

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

빠른 시작

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

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

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

자동 설정 기능

setup 명령어는 다음을 자동으로 처리합니다:

1. Service Account 키 파일 자동 탐지 - 현재 폴더에서 JSON 파일 스캔
2. GA4 연결 테스트 - Property ID와 키 파일 검증
3. Claude Code MCP 자동 등록 - claude mcp add 명령어로 자동 설정

  Careerly GA4 MCP Server
  ─────────────────────────────────────

✔ GA4 Property ID 517059569
✔ 1개의 Service Account 키 파일 발견
✔ 사용할 키 파일 선택 my-project-key.json (my-project-id)
✔ 연결 성공!
✔ Claude Code MCP 서버 등록 완료

  ✓ 설정 완료!

사전 준비

1. Google Cloud 설정

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

2. GA4 권한 설정

1. GA4 Admin > 속성 설정 > 속성 액세스 관리
2. 서비스 계정 이메일 추가 (뷰어/읽기 전용 권한)

Tip: Service Account 이메일은 JSON 키 파일의 client_email 필드에서 확인할 수 있습니다.

기능

| Tool | 설명 | |------|------| | ga4_query | GA4 데이터 조회 + 인사이트 생성 | | ga4_metadata | 지표/차원 목록 확인 | | ga4_status | 연결 상태 확인 |

사용 예시

Claude Code에서 자연어로 질문:

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

CLI 명령어

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

# 초기 설정 (자동 키 파일 탐지 + Claude Code 자동 등록)
npx careerly-ga4-mcp setup

# 서버 정보 확인
npx careerly-ga4-mcp info

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

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

인터랙티브 메뉴

npx careerly-ga4-mcp

  Careerly GA4 MCP Server
  ─────────────────────────────────────

Status:      ✓ connected
Property ID: 123456789
Credentials: ~/project/service-account.json
Tools:       3 tools

? 선택하세요
❯ View tools
  Reconnect
  Test connection
  Disable

수동 설정

Claude CLI로 추가

claude mcp add careerly-ga4 \
  -s user \
  -e GA4_PROPERTY_ID=123456789 \
  -e GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json \
  -- npx -y careerly-ga4-mcp serve

설정 파일 직접 수정

~/.claude/settings.local.json에 직접 추가:

{
  "mcpServers": {
    "careerly-ga4": {
      "command": "npx",
      "args": ["-y", "careerly-ga4-mcp", "serve"],
      "env": {
        "GA4_PROPERTY_ID": "123456789",
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account.json"
      }
    }
  }
}

문제 해결

MCP 서버가 /mcp에 안 보여요

1. Claude Code를 완전히 종료 후 재시작
2. 설정 확인: claude mcp list
3. 재설정: npx careerly-ga4-mcp setup

PERMISSION_DENIED 에러

GA4에 Service Account 권한이 없습니다:

1. GA4 Admin > 속성 설정 > 속성 액세스 관리
2. Service Account 이메일 추가 (JSON의 client_email)
3. 역할: 뷰어 (읽기 전용)

설정 삭제

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

# 또는 인터랙티브 메뉴에서
npx careerly-ga4-mcp
# → Disable 선택

Tool 스키마

ga4_query

{
  metrics: string[]      // 필수: ["sessions", "totalUsers", "conversions"]
  dimensions?: string[]  // 선택: ["date", "sessionDefaultChannelGroup"]
  startDate?: string     // 기본: "7daysAgo"
  endDate?: string       // 기본: "today"
  datePreset?: string    // "last_7_days", "last_30_days" 등
  limit?: number         // 기본: 10
}

지표 (Metrics)

| 지표 | 설명 | |------|------| | sessions | 세션 수 | | totalUsers | 전체 사용자 | | newUsers | 신규 사용자 | | activeUsers | 활성 사용자 | | bounceRate | 이탈률 | | conversions | 전환 수 | | screenPageViews | 페이지뷰 | | engagementRate | 참여율 |

차원 (Dimensions)

| 차원 | 설명 | |------|------| | date | 날짜 | | sessionDefaultChannelGroup | 채널 | | sessionSourceMedium | 소스/매체 | | sessionCampaignName | 캠페인 | | landingPage | 랜딩 페이지 | | deviceCategory | 디바이스 | | country | 국가 |

개발

# 의존성 설치
npm install

# 빌드
npm run build

# 개발 모드
npm run dev

# 타입 체크
npm run typecheck

라이선스

MIT