Skip to main content
Glama
deenesjakoruzh
prashantdasari-tech

ga4-mcp-worker

by prashantdasari-tech
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

ga4-mcp-worker

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 기반 검증만 되어 있습니다.

인증 모드: 사용자별 OAuth

각 팀원이 자신의 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 내부 동작. 광범위한 롤아웃 전에 읽으세요.

docs/IMPLEMENTATION-NOTES.md

이 구현이 올바르게 처리하는 함정(gotchas), 테스트된 것과 되지 않은 것, 그리고 운영 비용.

src/index.ts

MCP 서버: 도구, fetch 헬퍼, 정규화기(normaliser), 라우터. 주석이 상세히 달려 있습니다.

src/google-oauth.ts

"Google로 로그인" 핸들러 — /authorize와 /callback. 주석이 상세히 달려 있습니다.

wrangler.toml

Worker 구성입니다. nodejs_compat에 유의 — 알아야 할 함정 참조.

.dev.vars.example

로컬 개발용 템플릿입니다. .dev.vars로 복사하세요(gitignore 처리됨).

Related MCP server: GA4 MCP Server

우리의 GA4 속성

속성 ID

이름

측정 ID

상태

314138239

새 zuddl 웹사이트 GA4 속성

G-JWBQ2Z84QF

표준(Canonical) — 다른 지시가 없는 한 이 속성을 사용하세요.

260479909

legacy

—

레거시. 과거 데이터 전용. 현재 보고에는 사용하지 마세요.

328977581

legacy

—

레거시. 과거 데이터 전용. 현재 보고에는 사용하지 마세요.

서버는 속성 무관(property-agnostic) 입니다: 모든 도구는 property_id를 받으며, 314138239 또는 "properties/314138239" 둘 다 사용할 수 있습니다. 전달되지 않으면 wrangler.toml의 DEFAULT_PROPERTY_ID로 대체되며, 이 값은 표준 속성으로 설정되어 있어 팀원이 번호를 외울 필요가 없습니다. 자격 증명으로 실제로 볼 수 있는 모든 것을 나열하려면 get_account_summaries를 호출하세요.

도구 (9개)

도구

메서드 + 엔드포인트

용도

run_report

POST analyticsdata.googleapis.com/v1beta/properties/{id}:runReport

핵심 도구. 과거 보고. 전체 파라미터를 지원합니다.

run_realtime_report

POST .../v1beta/properties/{id}:runRealtimeReport

최근 ~30분. 별도의 더 작은 스키마.

run_funnel_report

POST .../v1alpha/properties/{id}:runFunnelReport

순서가 있는 단계 시퀀스와 이탈(drop-off) 분석.

run_conversions_report

POST .../v1alpha/properties/{id}:runReport

전환, 광고비, ROAS, 어트리뷰션 모델링. 필드 목록이 제한됨.

get_custom_dimensions_and_metrics

GET .../v1beta/properties/{id}/metadata

커스텀 필드를 쿼리 가능한 apiName 과 함께 제공. 커스텀 필드 사용 전에 호출하세요.

get_account_summaries

GET analyticsadmin.googleapis.com/v1beta/accountSummaries

이 자격 증명으로 읽을 수 있는 모든 것. 인수 없음.

get_property_details

GET .../v1beta/properties/{id}

타임존, 통화, 서비스 수준. 타임존이 날짜 불일치를 설명해 줍니다.

list_property_annotations

GET .../v1alpha/properties/{id}/reportingDataAnnotations

지표 상승·하락을 설명하는 날짜가 있는 메모.

list_google_ads_links

GET .../v1beta/properties/{id}/googleAdsLinks

연결된 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를 제외한 동일한 형태를 받습니다.

도구 설명은 의도적으로 깁니다 — 모든 필터 형태에 대한 실제 예시가 포함되어 있으며, 모델이 요청 형식을 배울 수 있는 유일한 곳입니다. 설명을 편집하는 것은 동작 변경으로 취급하세요.

엔드포인트

엔드포인트

인증

용도

POST /mcp

OAuth bearer token

MCP 연결(Streamable HTTP). /sse는 없습니다.

GET /authorize, POST /token, POST /register

—

OAuth 엔드포인트, @cloudflare/workers-oauth-provider로 구현됨.

GET /callback

—

Google 로그인 후 이곳으로 리다이렉트됩니다. 사람이 직접 열어볼 곳이 아닙니다.

GET /health

없음

상태 확인. 200 {"status":"ok","auth":"oauth", ...} 또는 503 + 세부 정보. 아래 메모 참조 — 공유 시크릿 모드보다 이 모드에서 의미가 더 제한적입니다. 데이터 유출 없음. 업타임 모니터를 연결하세요.

GET /

없음

현재 인증 모드를 알려주는 일반 텍스트 상태 배너.

그 외에는 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))를 보내므로 할당량 사용을 추적할 수 있습니다.

읽기 전용 강제

독립된 세 개의 계층이 모두 존재합니다.

  1. OAuth 범위 — 예전 공유 토큰이든 팀원 개인 토큰이든 모든 토큰은 https://www.googleapis.com/auth/analytics.readonly만 요청하며 그 외의 것은 없습니다(OAuth 모드에서 신원 확인용 openid/email을 추가하지만, 데이터 접근 권한은 부여하지 않습니다 — src/google-oauth.ts 참조). Google이 서버에서 쓰기를 거부합니다. 이것이 실제 보증입니다. SETUP-GUIDE.md에 tokeninfo로 검증하는 방법이 안내되어 있습니다.

  2. 엔드포인트 허용 목록 — 두 개의 fetch 헬퍼에서 네트워크 호출 전에 앵커된 정규식으로 검사합니다. 나중에 쓰기 엔드포인트를 추가하는 편집은 네트워크 요청 대신 예외를 던지게 됩니다.

  3. 변경 동작 없음 — 코드베이스 어디에도 PATCH, PUT, DELETE가 없습니다. fetch 호출 지점은 정확히 세 개입니다: 토큰 발급(POST), gaGet(GET), gaPost(POST).

:runReport, :runRealtimeReport, :runFunnelReport는 HTTP POST지만 쿼리입니다 — 쿼리 문자열에는 담기 너무 커서 요청 본문에 보고서 정의를 담아 보냅니다. GA4에서 아무것도 생성되거나 변경되지 않습니다.

빠른 명령

npm install
npm run typecheck && npm run dry-run
npm run deploy
npm run tail
curl -s https://ga4-mcp-worker.YOUR-SUBDOMAIN.workers.dev/health

두 인증 모드 모두 필요한 두 개의 시크릿을 설정합니다(대화식으로 붙여넣으세요 — 파이핑하면 값이 변형됩니다):

npx wrangler secret put GOOGLE_CLIENT_ID
npx wrangler secret put GOOGLE_CLIENT_SECRET

Claude Code에서 연결 — 로그인은 브라우저를 통해 이루어지므로 헤더가 필요 없습니다:

claude mcp add --transport http --scope user ga4 https://ga4-mcp-worker.YOUR-SUBDOMAIN.workers.dev/mcp

그런 다음 대화형 claude 세션에서 /mcp를 실행하고 ga4를 선택한 후 Google로 로그인하세요.

더 보기

This server cannot be installed

F
license - not found
Not graded
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

  • Google Analytics MCP Server

    surendranb
    A
    license
    A
    quality
    B
    maintenance
    Connects Google Analytics 4 data to Claude, Cursor and other MCP clients, enabling natural language queries of website traffic, user behavior, and analytics data with access to 200+ GA4 dimensions and metrics.
    10
    235
    MIT

  • GA4 MCP Server

    luminarylane
    A
    license
    A
    quality
    B
    maintenance
    Connects MCP clients like Claude Desktop to Google Analytics 4 Data API, enabling natural language queries for reports, top pages, traffic sources, conversions, realtime users, and period comparisons.
    7
    MIT

  • Google Analytics MCP Server

    rinaldofesta
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables querying Google Analytics 4 data using natural language through MCP clients like Claude and Cursor, supporting 200+ dimensions and metrics for traffic, user behavior, and e-commerce analysis.
    MIT

View all related MCP servers

Related MCP Connectors

  • WHOOP — MissingMCP

    WHOOP recovery, strain, sleep and workouts in Claude via official WHOOP OAuth. Free, open source.

  • ConvRadar

    GA4 conversion analyst inside Claude — funnel drops, traffic anomalies, device gaps, with numbers.

  • Fitness AI Connector

    Garmin data in Claude & ChatGPT via the Garmin Health API. OAuth sign-in, no password sharing.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/prashantdasari-tech/ga4-mcp-worker'

If you have feedback or need assistance with the MCP directory API, please join our Discord server