# GA4 MCP Server
Google Analytics 4 (GA4) のデータを Claude などの LLM から取得・分析できる MCP (Model Context Protocol) サーバーです。
## 特徴
- **20種類の分析ツール**: 単純なデータ取得だけでなく、実用的な分析ツールを多数搭載
- **日本語対応**: 出力結果は日本語でフォーマット（例: "2分34秒", "45.2%"）
- **柔軟な期間指定**: 相対日付（`7daysAgo`, `yesterday`）と絶対日付の両方に対応
- **即座にインサイト**: LLMが直接解釈しやすい形式でデータを返却
## 必要要件
- Node.js 18以上
- GA4 プロパティへのアクセス権を持つ Google アカウント
## インストール
```bash
cd ga4-mcp-server
npm install
npm run build
```
## 認証設定
### 方法1: gcloud CLI を使う（推奨・簡単）
サービスアカウント不要で、自分の Google アカウントで認証できます。
#### 1. gcloud CLI をインストール
```bash
# Windows (winget)
winget install Google.CloudSDK
# または https://cloud.google.com/sdk/docs/install からダウンロード
```
#### 2. 認証を実行
```bash
gcloud auth application-default login --scopes="https://www.googleapis.com/auth/analytics.readonly"
```
ブラウザが開くので、GA4 にアクセス権のある Google アカウントでログインするだけ！
これだけで完了です。`GOOGLE_APPLICATION_CREDENTIALS` の設定は不要です。
---
### 方法2: サービスアカウントを使う（本番環境向け）
チーム共有や本番環境では、サービスアカウントを使用します。
#### 1. Google Cloud Console でサービスアカウントを作成
1. [Google Cloud Console](https://console.cloud.google.com) にアクセス
2. プロジェクトを選択（または新規作成）
3. 「IAM と管理」→「サービスアカウント」→「サービスアカウントを作成」
4. 名前を入力して作成
5. 「キー」タブ →「鍵を追加」→「新しい鍵を作成」→ JSON形式でダウンロード
#### 2. API の有効化
「APIとサービス」→「ライブラリ」で以下を有効化:
- Google Analytics Data API
- Google Analytics Admin API
#### 3. GA4 プロパティへのアクセス権付与
1. [Google Analytics](https://analytics.google.com) にアクセス
2. 「管理」→「プロパティのアクセス管理」
3. サービスアカウントのメールアドレス（`xxx@xxx.iam.gserviceaccount.com`）を「閲覧者」として追加
## MCP 設定
### gcloud CLI 認証を使う場合（推奨）
```json
{
"mcpServers": {
"ga4": {
"command": "node",
"args": ["/path/to/ga4-mcp-server/dist/index.js"],
"env": {
"GA4_PROPERTY_ID": "123456789"
}
}
}
}
```
### サービスアカウントを使う場合
```json
{
"mcpServers": {
"ga4": {
"command": "node",
"args": ["/path/to/ga4-mcp-server/dist/index.js"],
"env": {
"GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account.json",
"GA4_PROPERTY_ID": "123456789"
}
}
}
}
```
### 設定ファイルの場所
| アプリ | 設定ファイル |
|--------|-------------|
| Claude Desktop (Mac) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |
| Cursor | `.cursor/mcp.json`（プロジェクトルート） |
## 環境変数
| 変数名 | 必須 | 説明 |
|--------|------|------|
| `GOOGLE_APPLICATION_CREDENTIALS` | × | サービスアカウントJSONキーのパス（gcloud CLI使用時は不要） |
| `GA4_PROPERTY_ID` | △ | デフォルトのGA4プロパティID（ツール実行時に指定も可） |
## 利用可能なツール
### 基本ツール（5個）
| ツール名 | 説明 |
|----------|------|
| `list_accounts` | アカウント・プロパティ一覧取得 |
| `get_property_details` | プロパティ詳細情報 |
| `run_report` | 汎用レポート実行（メインツール） |
| `run_realtime_report` | リアルタイムレポート |
| `get_metadata` | 利用可能なディメンション・メトリクス一覧 |
### 分析ツール（15個）
| ツール名 | 説明 |
|----------|------|
| `get_traffic_summary` | トラフィックサマリー（PV/UU/セッション等） |
| `get_top_pages` | 人気ページランキング |
| `get_traffic_sources` | 流入元分析 |
| `get_device_breakdown` | デバイス別アクセス比率 |
| `get_geo_breakdown` | 地域別アクセス分析 |
| `compare_periods` | 期間比較（前週比、前月比など） |
| `get_landing_pages` | ランディングページ分析 |
| `get_exit_pages` | 離脱ページ分析 |
| `get_user_journey` | ユーザージャーニー（ページ遷移） |
| `get_conversion_funnel` | コンバージョンファネル分析 |
| `get_hourly_traffic` | 時間帯別アクセス分析 |
| `get_daily_trend` | 日別トレンド |
| `get_new_vs_returning` | 新規 vs リピーター分析 |
| `get_engagement_metrics` | エンゲージメント指標 |
| `get_search_terms` | サイト内検索キーワード |
## 使用例
### 基本的な質問
```
「今日のPV数を教えて」
→ get_traffic_summary (period: "today")
「今リアルタイムで何人見てる？」
→ run_realtime_report
```
### ランキング系
```
「過去7日間のアクセス数が多いページTOP10」
→ get_top_pages (period: "7days", limit: 10)
「どこからアクセスが来てる？」
→ get_traffic_sources (period: "7days", groupBy: "channel")
```
### 比較・分析系
```
「先週と今週を比較して」
→ compare_periods (comparisonType: "previousPeriod", period: "7days")
「モバイルとPCの比率は？」
→ get_device_breakdown (period: "7days")
```
### 深堀り分析
```
「何時頃にアクセスが多い？」
→ get_hourly_traffic (period: "7days")
「このページを見た人は次にどこに行く？」
→ get_user_journey (pagePath: "/product/123", direction: "next")
```
## 開発
```bash
# 開発モード（ファイル変更を監視してリビルド）
npm run dev
# ビルド
npm run build
# 型チェック
npm run typecheck
```
## 注意事項
1. **レート制限**: GA4 Data API には 1 プロジェクトあたり 1 日 50,000 リクエストの制限があります
2. **データの遅延**: GA4のデータは通常24-48時間の遅延があります（リアルタイムレポートを除く）
3. **ファネル分析の制限**: GA4 Data APIでは真のファネル分析に制限があります。より正確な分析にはBigQuery Exportが必要です
## ライセンス
MIT
