GA4 API 켜고 Claude Code 에 공식 GA MCP 붙이기

GA4 의 Data API 와 Admin API 를 켜고, gcloud ADC 로 읽기 전용 자격 증명을 만들었다. 그다음 구글 공식 MCP 서버를 uvx 로 띄워 claude mcp add --scope user 로 등록했다. 이 방식은 서비스 계정 키 파일이 필요 없다. 공식 할당량 문서에는 요금 항목이 없고, 표준 속성 하나에 하루 20만 토큰 한도만 있다.

01 왜 공식 서버와 ADC 를 골랐나

MCP(Model Context Protocol)는 Claude 같은 AI 가 외부 도구를 부르는 규약이다. 참고한 블로그 글은 커뮤니티 GA 서버에 서비스 계정 키를 넣는 방식이었다. JSON 키 파일은 다시 내려받을 수 없어 따로 보관해야 한다. 개인키 문자열을 설정 화면에 옮겨 붙이는 단계도 있다.

구글이 관리하는 google-analytics-mcp 는 ADC 를 읽는다. ADC(Application Default Credentials)는 구글 라이브러리가 자격 증명을 정해진 순서로 찾아 쓰는 방식이다. 키 파일 대신 구글 계정으로 한 번 로그인하면 된다. 서버는 파이썬 3.10 이상에서 돌고, run_report·run_realtime_report 같은 조회 도구를 준다.

02 API 두 개를 먼저 켠다

Cloud 프로젝트에서 Google Analytics Admin API 와 Data API 를 켠다. Admin API 는 계정·속성 같은 설정 데이터를, Data API 는 보고서를 맡는다. 콘솔의 API 라이브러리에서 켜도 되고, gcloud 한 줄로도 된다.

bash

gcloud services enable \
  analyticsadmin.googleapis.com \
  analyticsdata.googleapis.com \
  --project YOUR_PROJECT_ID

03 ADC 는 읽기 전용 범위로 만든다

공식 README 의 명령은 analytics.readonly 와 cloud-platform 두 범위를 요청한다. --client-id-file 에는 직접 만든 OAuth 클라이언트 ID 파일을 넘긴다. 로그인하는 계정은 대상 GA 속성에 접근 권한이 있어야 한다.

bash

gcloud auth application-default login \
  --scopes https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/cloud-platform \
  --client-id-file=YOUR_CLIENT_JSON_FILE

브라우저 로그인이 끝나면 자격 증명 파일 경로가 출력된다. 구글 문서 기준 리눅스·macOS 의 기본 위치는 아래와 같다.

text

$HOME/.config/gcloud/application_default_credentials.json

gcloud 문서에 따르면 --client-id-file 을 쓰면 할당량 프로젝트가 ADC 에 기록되지 않는다. 공식 README 도 등록 단계에서 프로젝트 ID 를 환경 변수로 따로 넘긴다. 그러니 다음 단계에서 프로젝트 ID 를 빠뜨리지 않는다.

04 uvx 로 띄우고 user 범위로 등록한다

README 는 pipx run analytics-mcp 로 서버를 띄운다. 여기서는 같은 패키지를 uvx 로 돌렸다. uvx 는 파이썬 도구를 설치하지 않고 임시 격리 환경에서 실행한다. 전역 파이썬 환경에 패키지가 쌓이지 않는다.

bash

claude mcp add analytics-mcp \
  --scope user \
  -e "GOOGLE_APPLICATION_CREDENTIALS=$HOME/.config/gcloud/application_default_credentials.json" \
  -e "GOOGLE_PROJECT_ID=YOUR_PROJECT_ID" \
  -- uvx analytics-mcp

Claude Code MCP 문서 기준으로 -- 뒤는 서버 명령으로 그대로 넘어간다. --scope user 로 등록하면 모든 프로젝트에서 이 서버를 불러온다. 설정은 ~/.claude.json 에 저장되고, 저장소에 공유되는 .mcp.json 에는 들어가지 않는다. 등록 뒤에는 아래 명령이나 Claude Code 안의 /mcp 로 연결을 확인한다.

bash

claude mcp list
claude mcp get analytics-mcp

05 비용 대신 토큰 할당량을 본다

Data API 할당량 문서에는 요금 항목이 없다. 대신 요청마다 토큰을 쓰고, 속성 단위로 한도가 걸린다. 표준 속성의 핵심(Core) 요청 한도는 다음과 같다.

항목	한도
속성당 하루 토큰	200,000
속성당 시간당 토큰	40,000
프로젝트·속성당 시간당 토큰	14,000
속성당 동시 요청	10

행 수가 많고 필터가 복잡할수록 토큰을 더 쓴다. 요청 본문에 "returnPropertyQuota": true 를 넣으면 응답에 쓴 양과 남은 양이 함께 온다. 시간당 한도는 프로젝트·속성당 값이 가장 빠듯하니 이것부터 본다.

06 배운 것: 키 파일 없이 붙이는 편이 낫다

키 파일을 없애려면 공식 서버의 기본 인증을 따르면 된다. ADC 를 쓰면 개인키를 설정에 붙일 일이 없고, 로그인 한 번으로 끝난다. 다만 README 명령은 cloud-platform 범위도 함께 받는다. 그래서 자격 증명 파일은 GA 조회보다 넓은 권한을 담는다고 보고 비밀처럼 다룬다.

실행기와 등록 범위는 README 와 달리 골라도 된다. README 가 pipx 를 써도 같은 패키지를 uvx 로 돌릴 수 있다. user 범위로 등록하면 저장소마다 다시 등록할 필요가 없고, 자격 증명 경로도 공유 설정 파일에 남지 않는다. 비용은 걱정하지 않고, 속성별 토큰 할당량만 챙기면 된다.