GA4 MCP 서버

프로덕션 준비 완료, 멀티 테넌트 Google Analytics 4 MCP 서버 (Claude용).

이것은 더 큰 플랫폼의 첫 번째 커넥터입니다. 공유 인프라(인증, 클라이언트, Google OAuth 토큰 저장소, 권한 부여, 로깅, 오류)는 재사용 가능합니다. GA4 관련 코드는 src/connectors/ga4 및 src/mcp/ga4 아래에 유지됩니다. 이것을 모놀리식 Google Marketing MCP로 취급하지 마십시오.

아키텍처

Claude
  |  MCP OAuth 2.1 + Streamable HTTP
  v
Next.js / Vercel  (/mcp)
  |-- MCP tools (ga4_*)
  |-- Authorization (client_members only)
  |-- GA4 service
  |-- Google OAuth token manager
  v
Supabase
  |-- clients
  |-- client_members   (application identity)
  |-- google_connections (Google credential, not app identity)
  |-- ga4_properties

애플리케이션 사용자는 Supabase Auth 사용자입니다. 테넌트 액세스는 오직 client_members(user_id, client_id, role)을 통해서만 가능합니다. Google에 연결된 계정은 클라이언트 소유 자격 증명이며 애플리케이션 사용자가 아닙니다.

로컬 설정

npm install
cp .env.example .env.local
# fill in the values documented below
npx supabase start   # or link a remote project
npx supabase db reset --local
npm run dev

http://localhost:3000을 열고, 애플리케이션 계정을 만들고, 클라이언트를 만든 다음 Google Analytics를 연결하십시오.

Google Cloud 설정

1. Google Cloud 프로젝트를 생성하거나 선택합니다.

2. Google Analytics Data API 및 Google Analytics Admin API를 활성화합니다.

3. OAuth 동의 화면을 구성합니다(외부 또는 내부).

4. OAuth 2.0 클라이언트 ID 자격 증명(웹 애플리케이션)을 생성합니다.

5. 승인된 리디렉션 URI:

   • 로컬: http://localhost:3000/api/auth/google/callback

   • 프로덕션: https://<your-domain>/api/auth/google/callback

6. GA4 범위만 요청합니다:

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

   • openid

   • email

이 커넥터에 DV360 또는 Google Ads 범위를 추가하지 마십시오.

GA4 설정

1. 이 앱에 이메일/비밀번호로 로그인합니다(애플리케이션 ID).

2. 클라이언트를 생성합니다(client_members에서 owner가 됩니다).

3. 선택적으로 다른 애플리케이션 사용자를 owner 또는 member로 추가합니다.

4. Connect Google Analytics를 클릭합니다. 이렇게 하면 Google 자격 증명이 클라이언트에 연결됩니다.

5. 해당 Google 계정에서 발견된 하나 이상의 GA4 속성을 연결합니다.

Connect를 클릭하지 않은 멤버도 client_members 행이 있으면 클라이언트를 쿼리할 수 있습니다.

Supabase 설정

이 저장소에는 supabase/migrations에 SQL 마이그레이션이 포함되어 있습니다. CLI로 생성하고 파일 이름을 임의로 만들지 마십시오.

로컬:

npx supabase start
npx supabase db reset --local

원격:

npx supabase link --project-ref <project-ref>
npx supabase db push

서비스 역할 키는 서버 전용입니다. SUPABASE_SERVICE_ROLE_KEY 또는 Google 갱신 토큰을 브라우저에 절대 노출하지 마십시오.

환경 변수

.env.example을 참조하십시오. 필수:

.env에 GA4 속성 ID를 넣지 마십시오. 속성은 Supabase의 클라이언트에 속합니다.

토큰 암호화 키 생성:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

MCP 설정 (Claude)

원격 엔드포인트:

https://<your-domain>/mcp

이 서버는 MCP OAuth 2.1을 구현합니다:

• 보호된 리소스 메타데이터: /.well-known/oauth-protected-resource

• 권한 부여 서버 메타데이터: /.well-known/oauth-authorization-server

• 권한 부여: /oauth/authorize (애플리케이션 로그인 + 동의)

• 토큰: /oauth/token (authorization_code + refresh_token, PKCE S256)

• 등록: /oauth/register (DCR 폴백)

• CIMD가 광고됨 (client_id_metadata_document_supported)

Claude에서: Settings → Connectors → Add custom connector → https://<your-domain>/mcp를 붙여넣습니다. Claude가 OAuth를 실행합니다. 승인 후 도구를 사용할 수 있습니다.

로컬 인스펙터:

npx @modelcontextprotocol/inspector

Streamable HTTP를 사용하여 http://localhost:3000/mcp에 연결합니다. OAuth 흐름에서 얻은 유효한 MCP Bearer 토큰이 여전히 필요합니다.

도구

모든 도구에는 client_id가 필요합니다. 속성 범위 도구에는 연결된 property_id도 필요합니다. 권한 부여는 Google이 호출되기 전에 항상 client_members를 확인합니다.

예시: ga4_run_report

{
  "client_id": "11111111-1111-1111-1111-111111111111",
  "property_id": "123456789",
  "date_start": "2026-08-01",
  "date_end": "2026-08-15",
  "dimensions": ["country"],
  "metrics": ["activeUsers", "sessions", "totalRevenue"],
  "limit": 10
}

예시: ga4_compare_periods

{
  "client_id": "11111111-1111-1111-1111-111111111111",
  "property_id": "123456789",
  "current_start": "2026-08-01",
  "current_end": "2026-08-15",
  "previous_start": "2026-07-17",
  "previous_end": "2026-07-31",
  "metrics": ["activeUsers", "sessions", "totalRevenue"]
}

그러면 Claude는 다음과 같은 질문에 답할 수 있습니다:

• 어제 사용자가 몇 명이었나요?

• 이번 달 상위 10개 국가

• 이번 달과 지난달 비교

• 지금 사이트에 활성 사용자가 몇 명인가요?

테스트

npm test

테스트는 모의 Google 및 Supabase를 사용합니다. 프로덕션 OAuth 토큰을 절대 사용하지 않습니다.

Vercel

Next.js 앱을 배포하고 동일한 환경 변수를 설정합니다. MCP_BASE_URL 및 GOOGLE_REDIRECT_URI는 프로덕션 도메인을 사용해야 합니다. /mcp 경로는 60초 최대 지속 시간으로 Node.js 런타임에서 실행됩니다.

프로젝트 레이아웃

src/
  auth/              application authentication
  authorization/     authorizeClient via client_members
  oauth/             Google OAuth + token manager
  mcp-oauth/         MCP OAuth 2.1 authorization server
  connectors/ga4/    Google Analytics APIs
  mcp/ga4/           MCP tools
  repositories/      Supabase data access
  app/mcp/           Streamable HTTP transport

향후 커넥터(DV360, Google Ads)는 src/connectors/<name> 및 src/mcp/<name>을 추가하고 공유 코어를 재사용해야 합니다. 일반적인 Google API 덤프 공간을 만들지 마십시오.