# 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