Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

Google 애널리틱스 MCP 서버 사용해 보기

Google 애널리틱스 모델 컨텍스트 프로토콜 (MCP) 서버를 사용하면 Google 애널리틱스 데이터를 Gemini와 같은 대규모 언어 모델 (LLM) 및 AI 에이전트에 연결할 수 있습니다. MCP 서버를 사용하여 자연어로 보고서를 쿼리하고, 속성 구성을 검사하고, 커스텀 분석 에이전트를 빌드할 수 있습니다.

MCP 서버 설정 GitHub에서 보기 설정 튜토리얼 보기

기본 요건

Google 애널리틱스 MCP 서버를 구성하기 전에 다음 요구사항을 완료하세요.

Python 및 패키지 실행기를 설치합니다.
- Python 3.10 이상을 설치합니다.
- pipx 또는 uv (uvx)를 설치하여 격리된 Python 환경에서 MCP 서버를 실행합니다.
에서 Google 애널리틱스 API를 사용 설정합니다.
- 프로젝트를 만들거나 선택합니다.
- 프로젝트에서 Google Analytics Admin API(analyticsadmin.googleapis.com)와 Google Analytics Data API(analyticsdata.googleapis.com)를 모두 사용 설정합니다.
```
gcloud services enable analyticsadmin.googleapis.com \
  analyticsdata.googleapis.com \
  --project=YOUR_PROJECT_ID
```
Google 애널리틱스 속성 액세스 권한 부여:
- Google 애널리틱스 UI에서 사용자 계정 또는 서비스 계정에 대상 Google 애널리틱스 속성에 대한 최소한 뷰어 역할(roles/analytics.viewer)을 부여합니다. 자세한 내용은 액세스 및 데이터 제한 관리를 참조하세요.

인증 설정

Google 애널리틱스 MCP 서버는 읽기 전용 Google 애널리틱스 OAuth 2.0 범위와 함께 애플리케이션 기본 사용자 인증 정보 (ADC)를 사용하여 인증합니다.

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

Google 사용자 계정 또는 서비스 계정을 사용하여 ADC를 구성할 수 있습니다.

옵션 1: 사용자 인증 정보로 인증

gcloud CLI를 설치 및 초기화합니다.

필수 범위로 gcloud auth application-default login를 실행합니다.

gcloud auth application-default login \
  --scopes="https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/cloud-platform"

다운로드한 OAuth 2.0 데스크톱 또는 웹 클라이언트 구성 파일을 사용하는 경우(OAuth 클라이언트 관리 참조) --client-id-file를 전달합니다.

gcloud auth application-default login \
  --scopes="https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/cloud-platform" \
  --client-id-file=YOUR_CLIENT_JSON_FILE

명령어가 완료되면 콘솔에 출력된 사용자 인증 정보 경로 (Credentials saved to file: [PATH_TO_CREDENTIALS_JSON])를 복사합니다. MCP 클라이언트를 구성할 때 GOOGLE_APPLICATION_CREDENTIALS에서 이 경로를 사용합니다.

옵션 2: 서비스 계정을 사용하여 인증

Google 애널리틱스 속성에 대한 보기 권한이 있는 서비스 계정으로 인증하려면 다음 안내를 따르세요.

서비스 계정 JSON 키 파일: MCP 클라이언트 구성에서 GOOGLE_APPLICATION_CREDENTIALS를 서비스 계정 JSON 파일의 절대 경로로 설정합니다.

서비스 계정 가장: gcloud CLI를 사용하여 서비스 계정을 가장하여 ADC 사용자 인증 정보를 생성합니다.

gcloud auth application-default login \
  --impersonate-service-account=SERVICE_ACCOUNT_EMAIL \
  --scopes="https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/cloud-platform"

MCP 클라이언트 구성

서버는 PyPI에 analytics-mcp로 게시되며 analytics-mcp 및 google-analytics-mcp 콘솔 스크립트를 모두 노출합니다.

다음 구성에서 다음을 바꿉니다.

PATH_TO_CREDENTIALS_JSON를 ADC 또는 서비스 계정 JSON 파일의 절대 경로로 바꿉니다.
YOUR_PROJECT_ID: Google 애널리틱스 API를 사용 설정한 프로젝트 ID

Antigravity CLI 및 Antigravity IDE

Antigravity CLI 또는 Antigravity IDE를 설치합니다.

analytics-mcp 서버를 ~/.gemini/config/mcp_config.json (또는 작업공간의 .agents/mcp_config.json)에 추가합니다.

{
  "mcpServers": {
    "analytics-mcp": {
      "command": "pipx",
      "args": ["run", "analytics-mcp"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON",
        "GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID"
      }
    }
  }
}

analytics-mcp가 연결되어 있는지 확인합니다.
- Antigravity CLI: agy를 실행한 다음 /mcp를 입력하여 구성된 MCP 서버를 확인합니다.
- Antigravity IDE: 설정 > 맞춤설정 > 설치된 MCP 서버를 열고 새로고침을 클릭합니다.

Claude Desktop 및 Claude Code

Claude Desktop의 경우 claude_desktop_config.json 파일(macOS의 경우 ~/Library/Application Support/Claude/claude_desktop_config.json, Windows의 경우 %APPDATA%\Claude\claude_desktop_config.json)에 서버를 추가합니다.

{
  "mcpServers": {
    "analytics-mcp": {
      "command": "pipx",
      "args": ["run", "analytics-mcp"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON",
        "GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID"
      }
    }
  }
}

Claude Code의 경우 명령줄 도구를 사용하여 서버를 등록합니다.

claude mcp add analytics-mcp \
  --scope user \
  -e GOOGLE_APPLICATION_CREDENTIALS="PATH_TO_CREDENTIALS_JSON" \
  -e GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID" \
  -- pipx run analytics-mcp

커서

프로젝트 디렉터리의 .cursor/mcp.json (또는 전역 구성의 경우 ~/.cursor/mcp.json)에 서버를 추가합니다. uvx 또는 pipx를 사용하여 google-analytics-mcp를 호출할 수 있습니다.

{
  "mcpServers": {
    "google-analytics-mcp": {
      "command": "uvx",
      "args": ["--from", "analytics-mcp", "google-analytics-mcp"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON",
        "GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID"
      }
    }
  }
}

uvx를 사용하여 GitHub에서 직접 최신 개발 버전을 실행하려면 "args"를 업데이트합니다.

"args": [
  "--from",
  "git+https://github.com/googleanalytics/google-analytics-mcp.git",
  "google-analytics-mcp"
]

또는 pipx를 사용하려면 "command"를 "pipx"로 변경하고 "args"를 다음과 같이 설정합니다.

"command": "pipx",
"args": [
  "run",
  "--spec",
  "git+https://github.com/googleanalytics/google-analytics-mcp.git",
  "google-analytics-mcp"
]

사용 가능한 MCP 도구

Google 애널리틱스 MCP 서버는 Admin API 및 Data API v1을 사용하여 MCP 클라이언트에 읽기 전용 도구를 노출합니다.

계정 및 속성 검색 (Admin API):
- get_account_summaries: 인증된 사용자가 액세스할 수 있는 Google 애널리틱스 계정 및 속성을 나열합니다(accountSummaries.list).
- get_property_details: 특정 Google 애널리틱스 속성 (properties.get)의 구성 세부정보를 반환합니다.
- list_google_ads_links: 속성의 Google Ads 계정 링크를 나열합니다 (properties.googleAdsLinks.list).
- list_property_annotations: 속성에 구성된 주석을 나열합니다(properties.reportingDataAnnotations.list).
보고 및 스키마 검사 (Data API v1):
- get_custom_dimensions_and_metrics: 속성에 정의된 맞춤 측정기준 및 맞춤 측정항목을 검색합니다 (getMetadata).
- run_report: 표준 Google 애널리틱스 보고서(runReport)를 실행합니다.
- run_realtime_report: Google 애널리틱스 실시간 보고서(runRealtimeReport)를 실행합니다.
- run_funnel_report: Google 애널리틱스 유입경로 탐색 분석 보고서를 실행합니다(runFunnelReport).
- run_conversions_report: 전환 실적 보고서 (runConversionsReport)를 실행합니다.

샘플 프롬프트

연결되면 AI 어시스턴트에게 다음과 같은 질문을 해 보세요.

어제 발생한 사용자 수는?
어제 최다 판매 제품은 무엇인가요?
월 마케팅 예산이 5,000달러인데 수익을 더 늘려야 합니다. 데이터 기반 마케팅 계획을 세울 수 있게 도와줘.
내 속성에 어떤 맞춤 측정기준과 맞춤 측정항목이 구성되어 있나요?
지난 90일 동안 내 Google 애널리틱스 속성에서 가장 인기 있는 이벤트는 무엇인가요?

문제 해결

다음 체크리스트를 사용하여 일반적인 설정 및 런타임 오류를 해결하세요.

403 PERMISSION_DENIED (API가 사용 설정되지 않았거나 속성 권한이 부족함):
- GOOGLE_CLOUD_PROJECT로 지정된 프로젝트에서 Google Analytics Admin API(analyticsadmin.googleapis.com)와 Google Analytics Data API(analyticsdata.googleapis.com)가 모두 사용 설정되어 있는지 확인합니다.
- 인증 사용자 또는 서비스 계정에 Google 애널리틱스 UI의 대상 Google 애널리틱스 속성에 대한 최소한의 뷰어 역할 (roles/analytics.viewer)이 있는지 확인합니다.
- 오류 상태에 Request had insufficient authentication scopes가 표시되면 https://www.googleapis.com/auth/analytics.readonly 및 https://www.googleapis.com/auth/cloud-platform 범위로 gcloud auth application-default login를 다시 실행합니다.
할당량 프로젝트 (GOOGLE_CLOUD_PROJECT) 또는 403 ACCESS_NOT_CONFIGURED 누락:
- 사용자 ADC 사용자 인증 정보로 인증된 요청에는 Google 애널리틱스 API가 사용 설정된 할당량 프로젝트가 필요합니다. MCP 서버의 env 구성에서 "GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID"를 설정하거나 ADC 파일에서 할당량 프로젝트를 설정합니다.
```
gcloud auth application-default set-quota-project YOUR_PROJECT_ID
```
401 UNAUTHENTICATED 또는 사용자 인증 정보 파일을 찾을 수 없음:
- GOOGLE_APPLICATION_CREDENTIALS에 절대 경로를 사용합니다 (예: /Users/username/.config/gcloud/application_default_credentials.json). 많은 MCP 호스트가 JSON 구성 파일 내에서 셸 변수를 확장하지 않으므로 ~ 또는 $HOME 변수를 사용하지 마세요.
- 사용자 인증 정보가 만료된 경우 gcloud auth application-default login을 다시 실행합니다.
서버 실행 실패 (spawn pipx ENOENT, uvx: command not found 또는 Python 버전 오류):
- Python 3.10 이상이 설치되어 있는지 확인합니다 (python3 --version).
- 데스크톱 GUI 애플리케이션 (예: Claude Desktop 및 Cursor)은 대화형 셸 PATH를 상속하지 않는 경우가 많습니다. "command"의 "pipx" 또는 "uvx"를 which pipx 또는 which uvx에서 반환된 절대 바이너리 경로 (예: /opt/homebrew/bin/pipx 또는 /Users/username/.local/bin/pipx)로 바꿉니다.