프로젝트 소개

GA4 Dashboard & MCP는 자체 호스팅 가능한 실시간 Google Analytics 4 대시보드이며, 선택적으로 AI 어시스턴트용 Model Context Protocol(MCP) 서버를 포함합니다. ## 대시보드 기능 - **실시간 분석**: 활성 사용자 모니터링, 속성 비교, 트래픽 레시피, API 할당량 추적. - **3D 상호작용 지구**: Three.js로 전 세계 국가별 실시간 웹사이트 활동을 시각화. `/globe`에서 접근 가능. - **트래픽 급증 감지**: 갑작스러운 유입 증가 자동 탐지 및 출처(참조, 직접, 캠페인) 분류. - **방문자 인사이트**: 신규/재방문자 퍼소나 카드, 장치 분포, 주요 지역. - **프라이버시 보호**: 대시보드에서 전체 URL 파라미터 및 쿼리 문자열 숨김. - **스마트 캐싱**: 디스크 및 메모리 캐싱 계층 + GA4 API 할당량 보존을 위한 백그라운드 속성 메타데이터 업데이트. - **초기 설정 페이지**: 자격 증명 없을 시 브라우저 내 설정 흐름으로 리디렉션. ## MCP 서버 독립적인 `mcp-server/` 패키지는 Claude Desktop, Antigravity, Cursor 등 MCP 호환 클라이언트에 GA4 Admin 및 Data API 도구를 노출합니다. 대시보드와 독립 운영되며 별도의 의존성과 자격 증명 필요. ## 필수 조건 - Node.js v18.0.0+ - pnpm 패키지 매니저 - Google Analytics Data API 및 Admin API 접근 권한이 있는 Google Cloud 서비스 계정 ## 설치 개요 1. 저장소 복제 후 `pnpm install` 실행. 2. Google Cloud 서비스 계정 생성, 필요한 API 활성화, JSON 키 파일 생성. 3. 서비스 계정에 GA4 속성 Viewer 권한 부여 후 JSON 키를 프로젝트 루트에 배치(또는 `.env`에서 `GA4_CREDENTIALS_PATH` 설정). 4. `pnpm dev`(개발) 또는 `pnpm start`(배포)로 앱 시작. 5. 선택: `.env.example` 복사, `GOOGLE_APPLICATION_CREDENTIALS` 키 파일 경로 지정, MCP 클라이언트 설정에 서버 추가. ## URL - 기본 대시보드: `http://localhost:3000` - 3D 지구: `http://localhost:3000/globe` - 분석 보기: `http://localhost:3000/analytics` ## 테스트 및 빌드 단위 테스트는 `pnpm test`, TypeScript 컴파일 검사는 `pnpm build`로 실행. MIT 라이선스 하에 배포됨.