ga-gsc-analytics

Google Analytics 4 및 Google Search Console 데이터(analytics.readonly + webmasters.readonly 범위)를 Claude Code / Codex에 노출하는 읽기 전용 MCP 서버입니다.

처음이신가요? ONBOARDING.md를 따라 제로에서 작동까지의 과정(Claude Code 설치, 자격 증명 얻기, 인증, 확인)을 진행하세요. 이 파일의 나머지 부분은 참고 자료입니다.

AI 에이전트: 이 파일은 AGENTS.md 역할도 합니다 — 설정은 여기서 시작하고, 도구 사용 방법(접근 확인, 기본 날짜 범위, GA4 vs. GSC 의미론, 프레젠테이션 전달 형식)은 skills/analyze-ga-gsc/SKILL.md를 읽으세요. 사용자에게 채팅에 자격 증명을 붙여넣도록 요청하지 마세요.

도구

• analytics_auth_start / analytics_auth_status — 로컬 OAuth 흐름 + 상태 확인

• analytics_list_sources — 인증된 계정에서 사용 가능한 GA4 속성 및 GSC 사이트 나열

• ga_run_report — GA4 보고서 실행

• gsc_query_search_analytics — Search Console 데이터 쿼리

• analytics_presentation_snapshot — 보고용 GA4 + GSC 결합 스냅샷

Related MCP server: BigQuery MCP Server

설정 (사용자별)

각 사용자는 자신의 Google 계정으로 인증하고 자신의 로컬 토큰을 유지합니다 — client_secret.json 비밀 또는 tokens.json을 기기 간에 공유하지 마세요.

1. Google Cloud OAuth 클라이언트: Google Cloud Console에서 OAuth 2.0 데스크톱 클라이언트를 생성(또는 기존 항목 재사용)하고 해당 client_secret.json을 다운로드하세요. 동의 화면이 "테스트" 게시 상태인 경우, 각 새 사용자의 Google 계정을 먼저 테스트 사용자로 추가하세요. 그렇지 않으면 인증이 access-denied로 실패합니다.

2. 자격 증명 배치: ~/.config/ga-gsc-analytics/client_secret.json에 배치하거나 GA_GSC_CLIENT_SECRET을 사용자 지정 경로로 지정하세요.

3. 데이터 접근 권한 부여: 인증하는 Google 계정은 대상 GA4 속성(Analytics Admin → 속성 접근 관리) 및 GSC 사이트(Search Console → 설정 → 사용자 및 권한)에 실제 권한이 있어야 합니다.

4. 서버 빌드 (mcp/server.mjs를 변경한 경우에만 필요; 저장소에는 사전 빌드된 mcp/server.bundle.cjs가 포함되어 있습니다):

pnpm install
pnpm run build   # bundles mcp/server.mjs -> mcp/server.bundle.cjs

5. MCP 서버 등록. 다음 중 하나를 사용하세요:

   • Claude Code, 사용자 수준: claude mcp add ga-gsc-analytics -- node /path/to/ga-gsc-analytics/mcp/server.bundle.cjs

   • Claude Code / Codex, 프로젝트 범위: 이 저장소에는 이미 상대 경로 .mcp.json({"mcpServers": {"ga_gsc_analytics": {"command": "node", "args": ["./mcp/server.bundle.cjs"]}}})이 포함되어 있습니다 — 프로젝트에 복사하거나 이 전체 폴더를 심볼릭 링크/벤더링하면 해당 프로젝트가 열릴 때 자동으로 인식됩니다.

6. 인증: AI 도구 내에서 analytics_auth_start 도구를 호출하세요 — 로컬 브라우저 OAuth 흐름이 열리고 ~/.config/ga-gsc-analytics/tokens.json에 기록됩니다.

7. 확인: analytics_auth_status를 호출(authorized: true로 보고되어야 함)한 다음 analytics_list_sources를 호출하여 예상 GA4 속성 / GSC 사이트가 표시되는지 확인하세요.

구성 재정의

개발

pnpm run check   # syntax check
pnpm test        # node --test tests/*.test.mjs