Google Analytics MCP

Google Analytics 4용 로컬 MCP 서버입니다. SEO 및 유료 광고 보고에 중점을 둔 도구들을 통해 GA4 Data API를 래핑합니다.

도구

설정

git clone https://github.com/ZLeventer/google-analytics-mcp-server.git
cd google-analytics-mcp-server
npm install
npm run build

자격 증명

.env.example을 .env로 복사하고 다음을 채우십시오:

• GA4_PROPERTY_ID — GA4 관리자 → 속성 설정에서 확인 가능한 숫자 속성 ID (예: 123456789). 측정 ID(G-XXXXXXX)가 아닙니다.

• GOOGLE_APPLICATION_CREDENTIALS — 서비스 계정 JSON 키 파일의 절대 경로.

서비스 계정 생성

1. console.cloud.google.com으로 이동 → 프로젝트 선택/생성

2. API 및 서비스 → 라이브러리 → Google Analytics Data API 활성화

3. IAM 및 관리자 → 서비스 계정 → 서비스 계정 만들기 (ga4-mcp 등으로 이름 지정)

4. 생성된 계정 → 키 → 키 추가 → 새 키 만들기 → JSON → 다운로드

5. JSON을 이 디렉토리에 service-account.json으로 저장 (이미 .gitignore에 포함됨)

6. GA4 → 관리자 → 속성 액세스 관리에서 + 클릭 → 서비스 계정 이메일(ga4-mcp@project-id.iam.gserviceaccount.com) 붙여넣기 → 뷰어 권한 할당

Google SDK는 GOOGLE_APPLICATION_CREDENTIALS를 자동으로 읽으므로 코드 변경이 필요 없습니다.

Claude Code에 설치

claude mcp add google-analytics \
  --env-file "/absolute/path/to/google-analytics-mcp-server/.env" \
  -- node "/absolute/path/to/google-analytics-mcp-server/dist/index.js"

또는 ~/.claude.json에 수동으로 추가:

{
  "mcpServers": {
    "google-analytics": {
      "command": "node",
      "args": ["/absolute/path/to/google-analytics-mcp-server/dist/index.js"],
      "env": {
        "GA4_PROPERTY_ID": "123456789",
        "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/google-analytics-mcp-server/service-account.json"
      }
    }
  }
}

설치 후 Claude Code를 재시작하십시오.

날짜 형식

모든 날짜 인수는 GA4 형식을 지원합니다:

• YYYY-MM-DD (예: 2026-04-01)

• NdaysAgo (예: 28daysAgo, 90daysAgo)

• yesterday, today

기본값: 28daysAgo → yesterday.

확인

자격 증명이 설정된 후:

node -e '
  import("./dist/tools/reports.js").then(m =>
    m.channelPerformance({ start_date: "7daysAgo", end_date: "yesterday", limit: 10 })
  ).then(r => console.log(JSON.stringify(r, null, 2)))
'

행이 반환되면 정상적으로 작동하는 것입니다. 예상되는 오류:

• GA4_PROPERTY_ID is not set — .env 확인

• PERMISSION_DENIED — 서비스 계정에 속성 뷰어 권한이 부여되지 않음

• 403 Google Analytics Data API has not been used — GCP 프로젝트에서 API 활성화

로드맵

• [ ] 필요 시 관리자 API 도구 (맞춤 측정기준, 전환 이벤트, 잠재고객 목록)

• [ ] 순위/노출수/CTR 데이터를 위한 보조 서버로서의 Search Console MCP (본 서버 보완)

• [ ] GA4 트래픽과 기업 정보(계정 수준 기여도)를 결합하기 위한 Demandbase MCP와 연동