mcp-ga4

Google Analytics 4용 MCP 서버 -- Claude를 통해 보고서, 실시간 데이터, 맞춤 측정기준, 속성 관리를 실행합니다.

기능

• 보고서, 실시간 데이터, 맞춤 측정기준/측정항목, 데이터 스트림, 피드백을 다루는 9가지 도구

• 두 가지 구성 모드: 단일 속성(환경 변수) 및 다중 클라이언트(config.json)

• 서비스 계정 및 OAuth 자격 증명 모두 지원

• 상대 날짜 지원(today, yesterday, 7daysAgo, 30daysAgo, 90daysAgo)

• 공식 Google SDK 기반에 복원력 패턴 적용

Related MCP server: Google Analytics 4 MCP Server

설치

npm install mcp-ga4

또는 저장소를 클론합니다:

git clone https://github.com/mharnett/mcp-ga4.git
cd mcp-ga4
npm install
npm run build

인증

mcp-ga4는 두 가지 자격 증명 유형을 지원합니다. 선택은 결정적이며 시작 시 한 번 수행됩니다: 명시적 키파일 / 서비스 계정이 우선하고, 그 다음 사용자 OAuth가 적용되며, 둘 다 구성되지 않으면 서버는 두 옵션을 모두 명시하는 명확한 온보딩 오류와 함께 종료됩니다. 코드에 머신 로컬 자격 증명 경로가 없으며 런타임 시 자동 장애 조치(failover)도 없습니다 -- 유일한 자격 증명 입력은 환경 변수와 (선택적으로) 사용자별 config.json입니다. (따라서 이후 403은 다른 자격 증명 유형으로의 조용한 전환이 아닌 API 오류로 표시됩니다.)

우선순위: 두 유형이 모두 구성된 경우 키파일 / 서비스 계정이 사용자 OAuth보다 우선합니다.

옵션 A: 서비스 계정(무인 / 서버 사용 권장)

항상 실행 중이거나 서버 배포에 사용합니다. GOOGLE_APPLICATION_CREDENTIALS(또는 config.json의 credentials_file)를 JSON 키파일로 지정합니다. 서비스 계정은 GA4 속성에 대한 액세스 권한이 부여되어 있어야 합니다 (Admin → Property Access Management → 서비스 계정 이메일을 최소 Viewer 권한으로 추가). 리프레시 토큰은 필요 없습니다 -- 서버가 키파일을 GA4 SDK에 직접 전달합니다:

GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

키파일은 실제 서비스 계정 키 또는 authorized_user OAuth 토큰 덤프일 수 있습니다 -- 둘 다 keyFile 옵션을 통해 허용됩니다.

옵션 B: 사용자 OAuth(개인 / 대화형 사용)

서버가 Google 사용자(본인의 GA4 로그인)로 작동하도록 하려면 이 옵션을 사용합니다. 본인의 Google OAuth 클라이언트를 가져와 리프레시 토큰을 한 번 생성합니다.

1. Google Cloud Console에서 데스크톱 앱 유형의 OAuth 2.0 클라이언트 ID를 생성합니다. Google Analytics Data API를 사용 설정합니다(맞춤 측정기준 도구를 사용하는 경우 Admin API도 사용 설정).

2. 클라이언트 자격 증명을 내보내고 토큰 헬퍼를 실행합니다(PKCE 사용, 브라우저 열기, 토큰을 stdout으로 출력):

   export GA4_CLIENT_ID=...            # from the Desktop-app client
   export GA4_CLIENT_SECRET=...
   node get-refresh-token.cjs          # or: npm run auth

   이 명령의 stdout을 공유 로그로 리디렉션하지 마십시오 -- 리프레시 토큰이 의도적으로 거기에 출력됩니다.

3. 출력된 GA4_REFRESH_TOKEN=...을 환경에 복사합니다. 런타임 시 서버는 다음 세 가지 환경 변수를 읽습니다:

   GA4_CLIENT_ID=...
   GA4_CLIENT_SECRET=...
   GA4_REFRESH_TOKEN=...

요청된 스코프는 config.json의 oauth.scope에서 읽습니다(아래 참조). 따라서 헬퍼와 실행 중인 서버가 부여된 권한에 대해 서로 다르게 인식할 일이 없습니다.

스코프(최소 권한)

스코프는 config.json의 oauth.scope에 있습니다. 커밋된 기본값은 다음과 같습니다:

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

analytics.edit은 ga4_create_custom_dimension이 Admin API를 통해 속성을 변경하기 때문에 필요합니다. 읽기 액세스만 필요한 경우 본인의 config.json에서 oauth.scope를 analytics.readonly만으로 재정의하고 헬퍼를 다시 실행하세요.

구성

보안: .mcp.json 파일을 공유하거나 git에 커밋하지 마십시오 -- API 자격 증명이 포함될 수 있습니다. .mcp.json을 .gitignore에 추가하세요.

모드 1: 단일 속성(환경 변수)

속성 ID와 위의 인증 유형 중 하나를 설정합니다:

GA4_PROPERTY_ID=123456789
# then EITHER the OAuth trio (GA4_CLIENT_ID/SECRET/REFRESH_TOKEN)
# OR a service account: GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

모드 2: 다중 클라이언트(config.json)

프로젝트 루트에 config.json을 생성하여 여러 GA4 속성을 프로젝트 디렉터리에 매핑합니다. 서버는 호출자의 작업 디렉터리를 기반으로 사용할 속성을 자동 감지합니다. 자격 증명은 환경에서 가져옵니다(위 옵션 A/B). config.json은 구성 전용 서비스 계정 설정을 위해 credentials_file 서비스 계정 경로를 선택적으로 포함할 수 있습니다.

{
  "oauth": {
    "scope": "https://www.googleapis.com/auth/analytics.readonly https://www.googleapis.com/auth/analytics.edit"
  },
  "clients": {
    "client-a": {
      "name": "Client A",
      "folder": "/path/to/client-a/project",
      "property_id": "123456789"
    },
    "client-b": {
      "name": "Client B",
      "folder": "/path/to/client-b/project",
      "property_id": "987654321"
    }
  }
}

사용법

Claude Code (.mcp.json)

단일 속성 모드:

{
  "mcpServers": {
    "ga4": {
      "command": "npx",
      "args": ["mcp-ga4"],
      "env": {
        "GA4_PROPERTY_ID": "123456789",
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/credentials.json"
      }
    }
  }
}

다중 클라이언트 모드:

{
  "mcpServers": {
    "ga4": {
      "command": "node",
      "args": ["/path/to/mcp-ga4/dist/index.js"]
    }
  }
}

Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json(macOS) 또는 %APPDATA%\Claude\claude_desktop_config.json(Windows)에 추가합니다.

일반적인 쿼리 패턴

상위 페이지: dimensions=pagePath, metrics=screenPageViews, order_by=screenPageViews

트래픽 소스: dimensions=sessionSource,sessionMedium, metrics=sessions,totalUsers

일별 추이: dimensions=date, metrics=sessions,totalUsers

캠페인 성과: dimensions=sessionCampaignName, metrics=sessions,conversions

기기별 분석: dimensions=deviceCategory, metrics=sessions,totalUsers

도구

날짜 형식

절대 날짜에는 YYYY-MM-DD를 사용하거나 다음 상대 단축어를 사용합니다:

• today

• yesterday

• 7daysAgo

• 30daysAgo

• 90daysAgo

일반적인 측정기준 및 측정항목

측정기준: date, dateHour, eventName, pagePath, pageTitle, sessionSource, sessionMedium, sessionCampaignName, country, city, deviceCategory, browser, operatingSystem, landingPage, pageReferrer, newVsReturning, firstUserSource, firstUserMedium, firstUserCampaignName

측정항목: sessions, totalUsers, newUsers, activeUsers, screenPageViews, eventCount, conversions, engagedSessions, engagementRate, averageSessionDuration, bounceRate, sessionsPerUser, screenPageViewsPerSession, userEngagementDuration

데이터 최신성

• 표준 보고서: 24-48시간 지연

• 실시간 보고서: 최근 30분만

아키텍처

기반 기술:

• @google-analytics/data -- 보고서용 GA4 Data API

• @google-analytics/admin -- 속성 관리를 위한 GA4 Admin API

• cockatiel -- 복원력(재시도, 회로 차단기)

• pino -- 구조화된 로깅

라이선스

MIT

작성자

Mark Harnett / drak-marketing 작성