GA4 Analytics MCP V2

Google Analytics 4용 멀티 운영자 커넥터로, Claude.ai Custom Connectors에서 사용하며 Google Cloud Run에 호스팅됩니다.

이것은 버전 2입니다. V1과는 별개의 애플리케이션입니다. V1의 시크릿, OAuth 클라이언트, Cloud Run 서비스, Git 리모트를 재사용하지 마세요.

Operator A or Operator B
  → same Claude Custom Connector URL
  → https://<v2-host>/mcp
  → MCP OAuth (Claude → V2)
  → Google OAuth (operator's own Google account)
  → operator credentials + active GA4 property in Firestore
  → GA4 Admin / Data APIs

로컬 stdio 서버도 Supabase도 없습니다.

아키텍처

두 개의 OAuth 레이어가 연결됩니다:

1. Claude → V2: MCP OAuth 2.1(보호 리소스 메타데이터, DCR, CIMD, PKCE).

2. V2 → Google: Google 로그인은 MCP 인증 내부에서 발생합니다. MCP 액세스 토큰 sub는 Google 계정 주체(sub)입니다. 이메일은 표시용입니다.

각 운영자는 다음을 보유합니다:

• 자체 암호화된 Google 리프레시 토큰

• 자체 접근 가능한 GA4 속성 목록(Google Admin API에서)

• 자체 유지되는 활성 속성

운영자 A는 운영자 B의 Google 자격 증명을 사용할 수 없으며, Google 계정 A가 접근할 수 없는 속성을 선택할 수 없습니다.

MCP 도구

propertyId가 생략되면 보고서 도구는 저장된 활성 속성을 사용합니다. 제공된 propertyId는 인증된 Google 계정이 접근할 수 있는 경우에만 허용되며, 이후 새로운 활성 속성이 됩니다.

로컬 개발

cd D:\MCP_Servers\Ga4McpV2
npm install
copy .env.example .env.local

.env.local에 V2 값을 입력하세요. V1 시크릿을 복사하지 마세요.

선택적 Firestore 에뮬레이터:

gcloud emulators firestore start --host-port=localhost:8080

.env.local에 FIRESTORE_EMULATOR_HOST=localhost:8080 및 FIRESTORE_PROJECT_ID를 설정하세요.

npm run dev
npm test
npm run build

• 앱: http://localhost:3000

• MCP: http://localhost:3000/mcp

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

• Google 콜백: http://localhost:3000/oauth/google/callback

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

환경 변수

V2는 GOOGLE_REFRESH_TOKEN 또는 MCP_AUTH_TOKEN을 사용하지 않습니다.

Google Cloud 구성

가능하면 새 Google Cloud 프로젝트를 사용하세요. V1과 프로젝트를 공유하는 경우에도 별도의 Cloud Run 서비스, Artifact Registry 저장소, OAuth 클라이언트, 시크릿을 생성하세요.

활성화:

• Cloud Run

• Cloud Build

• Artifact Registry

• Firestore

• Secret Manager

• Google Analytics Admin API

• Google Analytics Data API

제안된 리소스 이름(자리 표시자 — 프로젝트에 맞게 교체):

• Cloud Run 서비스: ga4-mcp-v2

• Artifact Registry: ga4-mcp-v2

• Firestore 컬렉션: operators

Cloud Run 서비스 계정에는 다음 권한이 있어야 합니다:

• V2 Firestore 데이터베이스에 대한 roles/datastore.user

• V2 시크릿에 대한 roles/secretmanager.secretAccessor만

서비스 계정에 Secret Manager 관리자 권한을 부여하거나 V1 시크릿에 대한 접근 권한을 부여하지 마세요.

Google OAuth 클라이언트(V2 전용)

새 OAuth 웹 애플리케이션을 생성하세요. V1 클라이언트를 수정하지 마세요.

동의 화면:

• 사용자 유형: 외부(Workspace 전용인 경우 내부)

• 앱 이름: GA4 MCP Connector V2와 같은 이름

• 범위:

  • openid

  • email

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

• 앱이 테스트 모드인 동안 테스트 사용자를 추가하세요.

• Analytics 범위 때문에 비테스트 사용자에게는 게시가 필요합니다.

승인된 리디렉션 URI:

https://<v2-cloud-run-url>/oauth/google/callback

로컬:

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

Claude Custom Connector

1. V2를 배포하고 APP_BASE_URL을 Cloud Run URL로 설정하세요.

2. Claude에서 Custom Connector를 추가하세요.

3. URL: https://<v2-host>/mcp

4. 각 운영자는 자신의 Claude 계정에서 Google 로그인을 완료합니다.

5. Google 계정에 GA4 속성이 여러 개인 경우 운영자가 하나를 선택합니다. 해당 선택은 전환할 때까지 유지됩니다.

테스트

npm test

단위 테스트는 다음을 다룹니다:

• MCP OAuth 메타데이터, DCR, PKCE, Google 바인딩 JWT sub

• 운영자 격리(자격 증명 및 속성 허용 목록)

• 영구 활성 속성

• 토큰 갱신 / 순환

• 취소된 Google 권한

• 구조화된 로그 리덕션

라이브 V1 자격 증명은 사용되지 않습니다.

배포(요청 시에만 실행)

문서 전용입니다. V1 배포는 그대로 유지해야 합니다.

.\scripts\cloud-run-setup.ps1 -ProjectId YOUR_V2_PROJECT_ID
.\scripts\cloud-run-deploy.ps1 -ProjectId YOUR_V2_PROJECT_ID
.\scripts\cloud-run-set-env.ps1 `
  -ProjectId YOUR_V2_PROJECT_ID `
  -AppBaseUrl https://YOUR_V2_CLOUD_RUN_URL `
  -GoogleClientId YOUR_V2_CLIENT_ID `
  -GoogleClientSecret YOUR_V2_CLIENT_SECRET `
  -McpTokenSecret YOUR_MCP_TOKEN_SECRET `
  -OauthStateSecret YOUR_OAUTH_STATE_SECRET `
  -TokenEncryptionKey YOUR_TOKEN_ENCRYPTION_KEY

서비스를 연결할 때 프로덕션 시크릿은 일반 텍스트 환경 변수 대신 Secret Manager 참조를 사용하는 것을 선호합니다.

배포 후:

1. V2 OAuth 클라이언트에 Cloud Run 콜백 URI를 추가하세요.

2. Firestore가 네이티브 모드로 생성되었는지 확인하세요.

3. Claude에서 https://<v2-host>/mcp를 추가하세요.

보안 고려 사항

• 리프레시 토큰은 Firestore에 쓰기 전에 AES-256-GCM으로 암호화됩니다.

• MCP 도구는 액세스 토큰, 리프레시 토큰, 인증 코드를 절대 반환하지 않습니다.

• 로그는 토큰, 시크릿, 쿠키, 인증 코드를 리덕션합니다.

• Claude의 속성 ID는 해당 운영자의 Admin API 목록과 대조하여 실시간으로 확인됩니다.

• 운영자 컨텍스트가 요청에 바인딩되지 않으면 도구는 실패합니다.

• 프로덕션에서는 HTTPS 전용 쿠키를 사용합니다.

Git

이 저장소는 V2 전용입니다. V1 리모트는 git@github.com:devopsbrandmirchi/Ga4McpServer.git이며 여기에 추가해서는 안 됩니다. V2를 게시할 준비가 되면 새 GitHub 저장소를 생성하세요.