Google Analytics + AdSense Remote MCP

Cloudflare Workers에서 실행되는 GA4 및 AdSense Management API v2의 읽기 전용 Remote MCP 서버입니다. HTTP 라우팅은 Hono, MCP transport는 createMcpHandler(), 클라이언트의 OAuth 인가는 Cloudflare Access Managed OAuth를 사용합니다.

하나의 Worker는 한 쌍의 Google OAuth refresh token에 고정되며, 해당 Google 계정이 읽을 수 있는 모든 GA4 속성과 AdSense 계정을 처리합니다. 도구 호출에서 OAuth 자격 증명, Google API 호스트, 쓰기 작업을 대체할 수 없습니다.

Cloudflare에 원클릭 배포

버튼은 이 공개 GitHub 리포지토리를 사용자 자신의 계정으로 복제하고, Worker 이름과 다음 설정을 입력하여 빌드 및 배포합니다.

• 비밀 설정: CF_ACCESS_TEAM_DOMAIN, CF_ACCESS_AUD

• Secret: GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_REFRESH_TOKEN

GOOGLE_REFRESH_TOKEN은 버튼을 누르기 전에 아래 절차에 따라 read-only scope만 승인하여 발급하세요. Cloudflare Access Application 및 Managed OAuth 활성화는 배포 후 사용자가 직접 수행합니다.

Related MCP server: Google Analytics MCP server on Cloudflare Workers

엔드포인트

MCP 도구

• ga4_run_report, ga4_run_realtime_report, ga4_run_pivot_report, ga4_run_funnel_report

• ga4_get_metadata, ga4_check_compatibility

• ga4_admin_read: GA4 Admin API v1alpha의 accountSummaries, accounts, properties 하위의 GET/list 작업.

• adsense_generate_report

• adsense_read: AdSense Management API v2의 accounts 하위의 GET/list 작업.

모든 도구는 read-only로 MCP에 주석 처리되며, 입력은 Zod로 검증됩니다. 외부 URL, 임의 HTTP 헤더, POST/PUT/PATCH/DELETE의 임의 실행은 허용하지 않습니다. Google의 원시 오류는 MCP 응답에 포함하지 않지만, 장애 조사를 위해 배포 대상 Cloudflare 계정의 Worker Logs에는 전체 내용을 출력합니다.

Google OAuth 준비

1. Google Cloud Project에서 Google Analytics Data API, Google Analytics Admin API, AdSense Management API를 활성화합니다.

2. OAuth 동의 화면을 설정하고, GA4의 https://www.googleapis.com/auth/analytics.readonly와 AdSense의 https://www.googleapis.com/auth/adsense.readonly만 요청합니다.

3. Credentials에서 OAuth Client ID를 만들고, Application type은 Desktop app을 선택합니다. AdSense는 service account를 지원하지 않으며, Installed Application flow가 필요합니다.

4. refresh token은 다시 표시되지 않을 수 있으므로, 발급 시 안전한 비밀번호 관리자에 보관합니다. 리포지토리, Issue, CI log, wrangler.jsonc에 두면 안 됩니다.

Google은 access token을 짧은 시간 내에 만료시킵니다. Worker는 각 MCP 도구 실행 시 refresh token grant를 사용하여 access token을 다시 얻으므로, Worker가 token을 영구 저장할 필요는 없습니다.

Python으로 refresh token 발급

Python 3.10 이상만으로 동작하며, 추가 패키지는 필요 없습니다. scripts/get_google_refresh_token.py는 PKCE를 사용하여 로컬 callback을 대기하고, 자격 증명, access token, refresh token을 파일에 저장하지 않습니다.

Google Cloud Console의 redirect URI 설정

이 Worker는 Google에서 직접 callback을 받지 않습니다. Credentials에서 만드는 OAuth client는 반드시 Desktop app으로 하세요. Desktop app에서는 Cloud Console의 Authorized redirect URIs나 Authorized JavaScript origins를 설정할 필요가 없습니다.

Python 스크립트는 실행 시 사용 가능한 로컬 포트를 선택하고, 예를 들어 다음과 같은 loopback redirect URI를 Google로 보냅니다.

http://127.0.0.1:54321/callback/

이것은 Google이 Desktop app용으로 허용하는 loopback callback입니다. https://<worker-host>/callback, https://<worker-host>/mcp, Cloudflare Access의 URL을 Google OAuth client의 redirect URI로 등록하면 안 됩니다. 또한 Web application형 OAuth client에서 이 스크립트를 사용하는 것도 피하세요.

python scripts/get_google_refresh_token.py

GOOGLE_CLIENT_ID와 GOOGLE_CLIENT_SECRET 입력을 요청합니다. 브라우저에서 Worker가 사용하는 Google 계정에 로그인하고, 다음 read-only scope만 승인하세요.

브라우저 승인을 취소하려면 대기 중인 터미널에서 Ctrl+C를 누르세요. 로컬 callback listener를 닫고, token을 저장하지 않고 종료합니다.

• https://www.googleapis.com/auth/analytics.readonly

• https://www.googleapis.com/auth/adsense.readonly

성공 시 표시되는 한 줄만 복사하여 Deploy Button의 GOOGLE_REFRESH_TOKEN Secret란 또는 다음 대화형 명령에 입력합니다.

pnpm wrangler secret put GOOGLE_REFRESH_TOKEN

Client ID / secret도 미설정이면 동일하게 설정합니다.

pnpm wrangler secret put GOOGLE_CLIENT_ID
pnpm wrangler secret put GOOGLE_CLIENT_SECRET

Google OAuth 동의 화면이 External + Testing 상태이면 refresh token은 일반적으로 7일 후 만료됩니다. 지속 사용 전에 Production으로 전환하고, Google이 요구하는 verification을 완료하세요. invalid_grant가 발생하면 Google 계정에서 본 앱의 액세스를 취소한 후 이 스크립트를 다시 실행하고 Worker Secret을 업데이트합니다.

로컬 개발

필요: Node.js 20 이상, Corepack, Cloudflare Zero Trust를 사용할 수 있는 Cloudflare 계정.

corepack enable
pnpm install
Copy-Item .dev.vars.example .dev.vars
pnpm check
pnpm dev --local

.dev.vars에 실제 Google credentials를 설정합니다. 이 파일은 Git에 추가하지 않습니다.

Cloudflare에 배포

1. wrangler.jsonc의 name, CF_ACCESS_TEAM_DOMAIN, CF_ACCESS_AUD를 자신의 Cloudflare Access 설정 값으로 변경합니다.

2. Secret을 개별적으로 설정합니다.

pnpm wrangler secret put GOOGLE_CLIENT_ID
pnpm wrangler secret put GOOGLE_CLIENT_SECRET
pnpm wrangler secret put GOOGLE_REFRESH_TOKEN
pnpm run deploy

3. Cloudflare Zero Trust Dashboard에서 Worker의 https://<worker-host>/mcp를 대상으로 MCP server application을 만듭니다.

4. 허용할 이메일 주소 또는 ID group의 Access Policy를 만들고, 대상 외 사용자를 거부합니다.

5. Advanced settings에서 Managed OAuth를 활성화합니다. Application Audience tag와 Team Domain이 Worker 설정 값과 일치하는지 확인합니다.

Cloudflare Access가 OAuth discovery, Dynamic Client Registration, Authorization Code Flow, PKCE, Access token 갱신을 담당합니다. Worker 내에 자체 /authorize, /token, /register를 추가하지 마세요.

MCP 클라이언트 연결

MCP endpoint는 https://<worker-host>/mcp입니다. 첫 연결 시 Cloudflare Access 로그인 및 인가가 열립니다.

• Inspector: npx @modelcontextprotocol/inspector@latest를 실행하여 endpoint를 연결하고, 모든 도구를 Scan / List Tools 합니다.

• Codex 등: OAuth 지원 Remote MCP 설정에 endpoint를 등록합니다.

• ChatGPT: Developer mode의 Custom MCP app / connector에 endpoint를 등록하고, OAuth 인가를 완료한 후 Tool Scan을 실행합니다. ChatGPT 사용 가능 여부는 계약 플랜, Workspace 설정, 지역에 따라 다릅니다.

검증

pnpm check

check는 ESLint, TypeScript, Vitest, Worker binding 형식 동기화, wrangler deploy --dry-run을 순서대로 실행합니다. 실제 Google 계정에 대한 조회는 자동 테스트하지 않습니다. 배포 후 Access를 통해 Inspector와 사용하는 MCP 클라이언트에서 GA4 report와 AdSense report를 각각 1건씩 실행하세요.

Google API 장애 조사

Google API 실패 시 Worker가 Cloudflare Workers Logs에 JSON 진단 이벤트를 출력합니다. Google의 HTTP 응답 본문, 요청 URL 및 본문, 예외 이름, 메시지, 스택 트레이스를 생략하지 않고 출력합니다. 이는 배포 대상 Cloudflare 계정의 로그 조회자만 볼 수 있는 디버그용 설정입니다. 로그를 외부로 전송, 공유, 공개할 경우 사전에 이 상세 로그를 비활성화하세요. MCP 응답에는 계속 포함하지 않습니다.

pnpm wrangler tail --format json

예: {"event":"google_request_failed","tool":"ga4_run_report","category":"google_api","upstreamStatus":403,"error":{"request":{"url":"..."},"responseBody":"...","stack":"..."}}. oauth_refresh는 refresh token 갱신 실패, google_api는 GA4 / AdSense API 거부, unexpected는 네트워크 등의 예기치 않은 실패입니다.

라이선스

MIT License