GA4 Analytics MCP

개인 Google Analytics 4 커넥터로, Google Cloud Run에서 호스팅되며 Claude.ai Custom Connectors용으로 제작되었습니다.

Claude.ai Custom Connector
  → https://ga4-mcp-xxxxx-uc.a.run.app/ga4mcp
  → Cloud Run
  → Google Analytics Data API
  → your GA4 properties

로컬 stdio 서버, npx 요구 사항, claude_desktop_config.json이 없습니다.

두 개의 인증 계층은 별도로 유지됩니다:

1. Claude → MCP: MCP OAuth (CIMD / DCR)

2. MCP → Google: GOOGLE_REFRESH_TOKEN에 저장된 Google OAuth 리프레시 토큰

MCP 도구

Related MCP server: Google Analytics MCP Server

로컬 개발

npm install
copy .env.example .env.local

.env.local을 작성한 후:

npm run dev

• 앱: http://localhost:3000

• MCP: http://localhost:3000/ga4mcp

• Google OAuth: http://localhost:3000/oauth/google

• 상태 확인: http://localhost:3000/health

npm test
npm run build

Claude.ai는 localhost에 접근할 수 없습니다. Custom Connector를 추가하기 전에 Cloud Run에 배포하세요.

Google Cloud 설정 (단일 프로젝트)

API, OAuth, Cloud Run에 동일한 Google Cloud 프로젝트를 사용하세요.

1. 설치 및 로그인

1. Google Cloud SDK를 설치합니다.

2. 실행:

gcloud auth login
gcloud auth application-default login

3. Google Cloud Console에서 프로젝트를 생성하거나 선택합니다.

gcloud config set project YOUR_PROJECT_ID

2. API 활성화

.\scripts\cloud-run-setup.ps1 -ProjectId YOUR_PROJECT_ID -Region us-central1

다음이 활성화됩니다:

• Cloud Run

• Cloud Build

• Artifact Registry

• Google Analytics Data API

• Google Analytics Admin API

또는 Console에서 활성화: APIs & Services → Library.

3. OAuth 동의 및 웹 클라이언트

이 Google OAuth 클라이언트는 Cloud Run이 GA4 데이터를 읽을 수 있도록 하기 위한 것입니다. Claude.ai Advanced Settings 클라이언트가 아닙니다.

1. APIs & Services → OAuth consent screen을 엽니다.

2. 사용자 유형: 개인 Gmail 계정의 경우 External.

3. 앱 이름: GA4 MCP.

4. Testing 모드로 유지하는 경우 테스트 사용자로 자신을 추가합니다.

5. 리프레시 토큰이 7일 후 만료되지 않도록 Production으로 게시합니다.

6. OAuth client ID 자격 증명을 생성합니다.

7. 애플리케이션 유형: Web application.

8. 승인된 리디렉션 URI (둘 다 추가):

   • http://localhost:3000/oauth/google/callback

   • https://ga4-mcp-XXXXXXXX-uc.a.run.app/oauth/google/callback
     (첫 배포 후 실제 Cloud Run URL 사용)

9. 이 앱에서 사용하는 범위:

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

10. 클라이언트 ID와 클라이언트 시크릿을 복사합니다. 커밋하지 마세요.

권한을 부여하는 Google 계정은 Claude가 쿼리해야 하는 GA4 속성에 이미 접근 권한이 있어야 합니다.

Cloud Run에 배포

기본 서비스 이름: ga4-mcp. 기본 리전: us-central1.

.\scripts\cloud-run-deploy.ps1 -ProjectId YOUR_PROJECT_ID -Region us-central1

스크립트가 출력:

https://ga4-mcp-XXXXXXXX-uc.a.run.app
https://ga4-mcp-XXXXXXXX-uc.a.run.app/ga4mcp
https://ga4-mcp-XXXXXXXX-uc.a.run.app/health
https://ga4-mcp-XXXXXXXX-uc.a.run.app/oauth/google/callback

서비스는 인증 없이 허용으로 배포됩니다. 이는 필수입니다. Claude.ai는 Anthropic(160.79.104.0/21)에서 연결합니다. 인증은 Cloud Run IAM이 아닌 MCP_AUTH_TOKEN / MCP OAuth입니다.

환경 변수 설정

.\scripts\cloud-run-set-env.ps1 `
  -ProjectId YOUR_PROJECT_ID `
  -AppBaseUrl "https://ga4-mcp-XXXXXXXX-uc.a.run.app" `
  -GoogleClientId "....apps.googleusercontent.com" `
  -GoogleClientSecret "...." `
  -McpAuthToken "a-long-random-string"

그런 다음 아직 추가하지 않은 경우 Google OAuth 클라이언트에 Cloud Run 콜백 URL을 추가합니다.

Google 연결

1. https://ga4-mcp-XXXXXXXX-uc.a.run.app/oauth/google을 엽니다.

2. MCP_AUTH_TOKEN을 입력합니다.

3. Google 계정으로 로그인합니다.

4. 성공 페이지에서 GOOGLE_REFRESH_TOKEN을 복사합니다.

5. 설정하고 Cloud Run이 새 리비전을 시작하도록 합니다:

.\scripts\cloud-run-set-env.ps1 `
  -ProjectId YOUR_PROJECT_ID `
  -AppBaseUrl "https://ga4-mcp-XXXXXXXX-uc.a.run.app" `
  -GoogleClientId "....apps.googleusercontent.com" `
  -GoogleClientSecret "...." `
  -McpAuthToken "a-long-random-string" `
  -GoogleRefreshToken "1//...."

Cloud Run은 컨테이너 내부에서 env 변수를 쓸 수 없습니다. 다른 서버리스 호스트와 동일한 규칙입니다.

서비스 확인

https://ga4-mcp-XXXXXXXX-uc.a.run.app/health

다음을 반환해야 합니다:

{"status":"ok"}

환경 변수

Cloud Run 서비스에 설정하세요. Git에 넣지 마세요.

선택적 Console 경로: Cloud Run → ga4-mcp → Edit & deploy new revision → Variables & secrets.

Claude.ai Custom Connector

1. /health가 {"status":"ok"}를 반환하는지 확인합니다.

2. Google OAuth를 완료하고 GOOGLE_REFRESH_TOKEN을 설정합니다.

3. Claude.ai에서 Customize → Connectors → Add custom connector를 엽니다.

4. 이름: GA4 Analytics

5. URL:

https://ga4-mcp-XXXXXXXX-uc.a.run.app/ga4mcp

6. Advanced OAuth Client ID / Secret은 비워둡니다.

7. Add를 클릭합니다.

8. + → Connectors에서 커넥터를 활성화합니다.

9. 첫 번째 GA4 도구 호출 시 Connect가 표시됩니다. 이 앱의 동의 페이지에 MCP_AUTH_TOKEN을 입력합니다 (Google 비밀번호가 아님).

10. 질문: How many users did I have yesterday?

수동 gcloud (스크립트를 사용하지 않으려는 경우)

gcloud artifacts repositories create ga4-mcp --repository-format=docker --location=us-central1
gcloud builds submit --config cloudbuild.yaml --substitutions=_REGION=us-central1
gcloud run services describe ga4-mcp --region us-central1 --format="value(status.url)"
gcloud run services update ga4-mcp --region us-central1 --update-env-vars APP_BASE_URL=https://...,GOOGLE_CLIENT_ID=...,GOOGLE_CLIENT_SECRET=...,GOOGLE_REDIRECT_URI=https://.../oauth/google/callback,MCP_AUTH_TOKEN=...

보안

• Google 토큰, 인증 코드, 클라이언트 시크릿, MCP JWT를 절대 로깅하지 마세요.

• MCP 도구는 절대 시크릿을 반환하지 않습니다.

• GOOGLE_REFRESH_TOKEN만 Cloud Run env 변수로 유지됩니다.

• Cloud Run 인그레스는 Claude가 연결할 수 있도록 공개 상태입니다. /ga4mcp 앞에 Cloud IAP / IAM 로그인을 추가하지 마세요.

• 길고 무작위한 MCP_AUTH_TOKEN을 생성하세요.

날짜

GA4에 변경 없이 전달: today, yesterday, 7daysAgo, 30daysAgo, 90daysAgo 또는 YYYY-MM-DD. date 측정기준은 YYYYMMDD로 반환됩니다.

알려진 제한 사항

• 하나의 Google 계정과 하나의 리프레시 토큰.

• Cloud Run은 런타임에 파일을 유지하거나 env 변수를 변경할 수 없습니다. GOOGLE_REFRESH_TOKEN을 설정하고 새 리비전을 배포하세요.

• Google Testing 모드 리프레시 토큰은 약 7일 후 만료됩니다.

• 실시간 데이터는 대략 최근 30분입니다.

• 보고서 크기는 10,000행으로 제한됩니다.

• min-instances가 0인 경우 콜드 스타트로 인해 몇 초가 추가될 수 있습니다.

Cloud Run용으로 추가된 파일