GA4 Analytics MCP

Claude.ai Custom Connectors용 개인 Google Analytics 4 커넥터입니다. 하나의 Google 계정, 하나의 MCP 서버, Vercel에 배포됩니다.

Claude.ai Custom Connector
  → https://<VERCEL_PROJECT_NAME>.vercel.app/ga4mcp
  → Vercel Streamable HTTP MCP
  → Google Analytics Data API
  → your GA4 properties

로컬 stdio 서버가 없고, npx 요구 사항이 없으며, claude_desktop_config.json도 없습니다.

두 가지 인증 계층은 분리되어 있습니다:

1. Claude → MCP: MCP OAuth (CIMD / DCR / 선택적 Advanced Settings 클라이언트)

2. MCP → Google: GOOGLE_REFRESH_TOKEN에 저장된 Google OAuth 갱신 토큰

MCP 도구

로컬 개발

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를 추가하기 전에 Vercel에 배포하세요.

Google Cloud 설정

이는 MCP 서버가 GA4 데이터를 읽을 수 있도록 하기 위한 것입니다. Claude.ai 커넥터 OAuth 클라이언트가 아닙니다.

1. Google Cloud 프로젝트를 만들거나 선택합니다.

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

3. Google Analytics Admin API를 활성화합니다.

4. OAuth 동의 화면을 구성합니다(개인 Gmail은 외부). 갱신 토큰이 7일 후 만료되지 않도록 프로덕션으로 게시합니다.

5. 웹 애플리케이션 OAuth 클라이언트를 만듭니다.

6. 승인된 리디렉션 URI:

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

   • https://<VERCEL_PROJECT_NAME>.vercel.app/oauth/google/callback

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

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

8. 클라이언트 ID와 시크릿을 환경 변수에 복사합니다.

그런 다음 /oauth/google에 방문하여 MCP_AUTH_TOKEN을 입력하고 GA4 속성을 소유한 Google 계정으로 로그인합니다.

• 로컬에서 갱신 토큰은 .env.local에 기록됩니다.

• Vercel에서는 GOOGLE_REFRESH_TOKEN을 프로젝트 환경 변수에 붙여넣고 재배포합니다.

환경 변수

Vercel

npm i -g vercel
vercel
vercel --prod

Vercel 프로젝트에 환경 변수를 추가합니다. 프로덕션에서 첫 번째 Google OAuth 후 GOOGLE_REFRESH_TOKEN을 설정하고 재배포합니다.

프로덕션에서 Deployment Protection / Vercel Authentication을 비활성화합니다. Claude.ai는 Anthropic의 네트워크(160.79.104.0/21)에서 연결합니다. /ga4mcp 앞에 Vercel SSO가 있으면 커넥터가 연결할 수 없습니다.

프로덕션 URL:

https://<VERCEL_PROJECT_NAME>.vercel.app/ga4mcp
https://<VERCEL_PROJECT_NAME>.vercel.app/oauth/google/callback
https://<VERCEL_PROJECT_NAME>.vercel.app/health

사용자 정의 도메인은 나중에 선택 사항입니다. 코드 변경이 필요 없도록 APP_BASE_URL을 계속 사용합니다.

Claude.ai Custom Connector

1. Vercel에 배포하고 https://<VERCEL_PROJECT_NAME>.vercel.app/health가 {"status":"ok"}를 반환하는지 확인합니다.

2. https://<VERCEL_PROJECT_NAME>.vercel.app/oauth/google에서 Google을 연결합니다.

3. Vercel 환경 변수에 GOOGLE_REFRESH_TOKEN을 넣고 재배포합니다.

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

5. 이름: GA4 Analytics

6. URL:

   https://<VERCEL_PROJECT_NAME>.vercel.app/ga4mcp

7. Advanced OAuth Client ID / Secret을 비워 둡니다. Claude는 이 서버의 인증 엔드포인트에 대해 CIMD를 사용합니다.

8. Add를 클릭합니다.

9. 채팅 + → Connectors 메뉴에서 커넥터를 활성화합니다.

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

11. 질문: 어제 사용자가 몇 명이었나요?

initialize와 tools/list는 공개되어 Claude가 도구를 발견할 수 있습니다. tools/call은 MCP OAuth가 완료될 때까지 WWW-Authenticate와 함께 HTTP 401을 반환합니다.

보안

• Google 토큰, 인증 코드, 클라이언트 시크릿 또는 MCP JWT를 절대 로깅하지 않습니다.

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

• Google 액세스 토큰은 저장되지 않습니다. GOOGLE_REFRESH_TOKEN만 환경 변수에 유지됩니다.

• Git에 시크릿을 넣지 마세요.

날짜

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

알려진 제한 사항

• 하나의 Google 계정과 하나의 갱신 토큰.

• Vercel은 런타임에 환경 변수를 쓸 수 없습니다. GOOGLE_REFRESH_TOKEN을 붙여넣고 재배포합니다.

• Google 테스트 모드 갱신 토큰은 약 7일 후 만료됩니다.

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

• 보고서 크기는 최대 10,000행입니다.

• 이 저장소에서 라이브 Claude.ai 클릭스루를 완료할 수 없습니다. 이를 위해서는 Claude 및 Vercel 계정이 필요합니다.