Cloudflare Workers에서 실행되는 읽기 전용 Google Analytics 4 MCP 서버입니다. 팀원들은 로컬에 아무것도 설치하지 않고 — Python도, gcloud도, ADC 파일도, 그리고 이 버전부터는 공유 비밀번호도 없이 — Claude에서 GA4를 조회할 수 있습니다. 서버를 추가하는 과정은 "Connect"를 클릭하고, 자신의 Google 계정으로 로그인하고, 본인 자격으로 GA4 질문에 답하는 것뿐입니다.
공식 googleanalytics/google-analytics-mcp stdio 서버의 도구 인터페이스를 그대로 반영하지만, Google의 클라이언트 라이브러리는 Workers 런타임에서 실행되지 않으므로 Google Analytics REST API를 직접 호출합니다.
먼저 읽으세요: docs/IMPLEMENTATION-NOTES.md § 테스트된 것과 테스트되지 않은 것. 실제 end-to-end 검증은 구현되어 있지만, 일부 영역(v1alpha 엔드포인트, 페이지네이션)은 아직 fixture 기반 검증만 되어 있습니다.
각 팀원이 자신의 Google 계정으로 로그인합니다. 공유 시크릿도 없고, 모두가 의존하는 단일 Google 자격 증명도 없습니다. 전체 설계와 폐지된 공유 시크릿 모드와의 차이점은 PRODUCTION.md § 1 및 docs/PRODUCTION-PART2.md § 8을 참조하세요. 로그인은 @zuddl.com Google 계정으로 제한됩니다(wrangler.toml의 ALLOWED_EMAIL_DOMAIN).
GOOGLE_CLIENT_ID와 GOOGLE_CLIENT_SECRET는 여전히 필요합니다. Google은 사용자 데이터를 요청하는 모든 앱이 등록되도록 요구하며, 이 두 값 이 그 등록이며 배포 시 한 번만 설정됩니다. 사라진 것은 직접 만들어두었던 refresh token과 팀원들이 예전에 공유해 사용하던 비밀번호입니다.
파일 | 설명 |
SETUP-GUIDE.md (+ 2부) | 처음 배포를 시작부터 설명합니다 — OAuth 사전 지식이 없어도 됩니다. Google 앱 만들기, 배포, 테스트, Claude 연결. 여기서 시작하세요. |
PRODUCTION.md (+ 2부) | identity 모델, 모니터링, GA4 할당량, 시크릿 로테이션, 로컬 개발, 런북(runbook), 보안 체크리스트, OAuth 내부 동작. 광범위한 롤아웃 전에 읽으세요. |
이 구현이 올바르게 처리하는 함정(gotchas), 테스트된 것과 되지 않은 것, 그리고 운영 비용. | |
| MCP 서버: 도구, fetch 헬퍼, 정규화기(normaliser), 라우터. 주석이 상세히 달려 있습니다. |
| "Google로 로그인" 핸들러 — |
| Worker 구성입니다. |
| 로컬 개발용 템플릿입니다. |
Related MCP server: GA4 MCP Server
속성 ID | 이름 | 측정 ID | 상태 |
| 새 zuddl 웹사이트 GA4 속성 |
| 표준(Canonical) — 다른 지시가 없는 한 이 속성을 사용하세요. |
| legacy | — | 레거시. 과거 데이터 전용. 현재 보고에는 사용하지 마세요. |
| legacy | — | 레거시. 과거 데이터 전용. 현재 보고에는 사용하지 마세요. |
서버는 속성 무관(property-agnostic) 입니다: 모든 도구는 property_id를 받으며, 314138239 또는 "properties/314138239" 둘 다 사용할 수 있습니다. 전달되지 않으면 wrangler.toml의 DEFAULT_PROPERTY_ID로 대체되며, 이 값은 표준 속성으로 설정되어 있어 팀원이 번호를 외울 필요가 없습니다. 자격 증명으로 실제로 볼 수 있는 모든 것을 나열하려면 get_account_summaries를 호출하세요.
도구 | 메서드 + 엔드포인트 | 용도 |
| POST | 핵심 도구. 과거 보고. 전체 파라미터를 지원합니다. |
| POST | 최근 ~30분. 별도의 더 작은 스키마. |
| POST | 순서가 있는 단계 시퀀스와 이탈(drop-off) 분석. |
| POST | 전환, 광고비, ROAS, 어트리뷰션 모델링. 필드 목록이 제한됨. |
| GET | 커스텀 필드를 쿼리 가능한 |
| GET | 이 자격 증명으로 읽을 수 있는 모든 것. 인수 없음. |
| GET | 타임존, 통화, 서비스 수준. 타임존이 날짜 불일치를 설명해 줍니다. |
| GET | 지표 상승·하락을 설명하는 날짜가 있는 메모. |
| GET | 연결된 Ads 계정. 광고 비용 지표에 데이터가 있을 수 있는지 확인. |
run_report는 공식 파라미터 전체를 받습니다: property_id, date_ranges(목록이므로 하나의 요청으로 기간 대비 비교 가능), dimensions, metrics, dimension_filter, metric_filter, order_bys, limit, offset, currency_code, return_property_quota. run_realtime_report는 date_ranges와 currency_code를 제외한 동일한 형태를 받습니다.
도구 설명은 의도적으로 깁니다 — 모든 필터 형태에 대한 실제 예시가 포함되어 있으며, 모델이 요청 형식을 배울 수 있는 유일한 곳입니다. 설명을 편집하는 것은 동작 변경으로 취급하세요.
엔드포인트 | 인증 | 용도 |
| OAuth bearer token | MCP 연결(Streamable HTTP). |
| — | OAuth 엔드포인트, |
| — | Google 로그인 후 이곳으로 리다이렉트됩니다. 사람이 직접 열어볼 곳이 아닙니다. |
| 없음 | 상태 확인. |
| 없음 | 현재 인증 모드를 알려주는 일반 텍스트 상태 배너. |
그 외에는 404를 반환합니다.
/health는 OAuth 모드에서 덜 증명합니다. 단일한 공유 자격 증명이 없으므로,200은 앱 등록이 구성되어 있고 그런트 저장소(OAUTH_KV)에 접근할 수 있다는 것만 확인할 뿐, 특정 사용자의 로그인이 여전히 유효한지는 확인하지 않습니다./health가 초록색이어도 개별 사용자의 그런트는 만료되거나 취소될 수 있습니다. 이것은 사용자별 인증에 본질적인 것이지 결함이 아닙니다.
Worker는 MCP 요청마다, 거부된 인증 시도마다, 도구 오류마다, 헬스 실패마다 JSON 로그 한 줄을 남기고, OAuth 관련 이벤트(oauth_authorize_redirect, oauth_authorized, oauth_domain_rejected 등)도 남깁니다. 토큰 자체가 로그에 남는 일은 없습니다. 모든 Google API 호출은 커스텀 User-Agent(ga4-mcp-worker/1.0.0 (+cloudflare-workers))를 보내므로 할당량 사용을 추적할 수 있습니다.
독립된 세 개의 계층이 모두 존재합니다.
OAuth 범위 — 예전 공유 토큰이든 팀원 개인 토큰이든 모든 토큰은 https://www.googleapis.com/auth/analytics.readonly만 요청하며 그 외의 것은 없습니다(OAuth 모드에서 신원 확인용 openid/email을 추가하지만, 데이터 접근 권한은 부여하지 않습니다 — src/google-oauth.ts 참조). Google이 서버에서 쓰기를 거부합니다. 이것이 실제 보증입니다. SETUP-GUIDE.md에 tokeninfo로 검증하는 방법이 안내되어 있습니다.
엔드포인트 허용 목록 — 두 개의 fetch 헬퍼에서 네트워크 호출 전에 앵커된 정규식으로 검사합니다. 나중에 쓰기 엔드포인트를 추가하는 편집은 네트워크 요청 대신 예외를 던지게 됩니다.
변경 동작 없음 — 코드베이스 어디에도 PATCH, PUT, DELETE가 없습니다. fetch 호출 지점은 정확히 세 개입니다: 토큰 발급(POST), gaGet(GET), gaPost(POST).
:runReport, :runRealtimeReport, :runFunnelReport는 HTTP POST지만 쿼리입니다 — 쿼리 문자열에는 담기 너무 커서 요청 본문에 보고서 정의를 담아 보냅니다. GA4에서 아무것도 생성되거나 변경되지 않습니다.
npm installnpm run typecheck && npm run dry-runnpm run deploynpm run tailcurl -s https://ga4-mcp-worker.YOUR-SUBDOMAIN.workers.dev/health두 인증 모드 모두 필요한 두 개의 시크릿을 설정합니다(대화식으로 붙여넣으세요 — 파이핑하면 값이 변형됩니다):
npx wrangler secret put GOOGLE_CLIENT_IDnpx wrangler secret put GOOGLE_CLIENT_SECRETClaude Code에서 연결 — 로그인은 브라우저를 통해 이루어지므로 헤더가 필요 없습니다:
claude mcp add --transport http --scope user ga4 https://ga4-mcp-worker.YOUR-SUBDOMAIN.workers.dev/mcp그런 다음 대화형 claude 세션에서 /mcp를 실행하고 ga4를 선택한 후 Google로 로그인하세요.
주의 사항, 테스트 커버리지, 실행 비용: docs/IMPLEMENTATION-NOTES.md
첫 배포 연습 방법: SETUP-GUIDE.md → 2부
강화, 모니터링 및 OAuth 런북: PRODUCTION.md → 2부
This server cannot be deployed
GA4, Google Ads and Search Console in Claude. Read-only OAuth, multi-account for agencies.
Read-only Google Analytics 4 MCP server for AI assistants.
Hosted MCP server for GA4, Google Ads and Search Console. Google OAuth, nothing to install.
Hosted BigQuery MCP server for Claude, ChatGPT and Cursor, with each action switched per account.