GA4のBigQueryをClaudeで分析し週次レポートを自動化する手順

GA4のBigQueryエクスポートを持っているなら、Claude CodeにBigQuery MCPサーバーをつないで日本語で問い合わせるだけで、週次のPVやコンバージョンの集計が取れます。毎週の実行は、cronからclaude -pを呼ぶ形で自動化できます。

ただし、GA4のエクスポートには独特のスキーマがあり、そのまま自然言語で聞くと数字がずれる場面があります。この記事では接続、スキーマの教え方、週次の問い合わせ、定例化までを順に書きます。BigQuery接続そのものの手順はBigQueryをClaudeで自然言語のまま分析するにあるので、ここはGA4に固有の部分を中心にします。

GA4のデータをClaudeに渡す経路は2つある

GA4のデータをClaude Codeから読む方法は、大きく2つに分かれます。

Google Analytics MCPサーバーは、Googleのリポジトリで公開されている実験的なローカルMCPサーバーです。提供されるツールは次のとおりです。

• get_account_summaries / get_property_details / list_google_ads_links
• run_report / run_funnel_report / get_custom_dimensions_and_metrics
• run_realtime_report

週次レポートの主役はBigQuery MCPサーバーに置き、APIは「このプロパティのカスタムディメンションは何か」といった構成の確認に使う、という分担が組み立てやすい形です。

エクスポートの前提と制限を先に押さえる

自動化の前に、エクスポート側の仕様を確認します。数字がずれる原因の多くはここにあります。

週次レポートで特に効くのは、次の2点です。

1. Dailyテーブルは後から更新される。 events_YYYYMMDDは、遅れて届くイベントを取り込むため、テーブル日付から2暦日と当日ぶん先まで更新され得ます。
2. プロパティのタイムゾーンが日付の基準になる。タイムゾーンを変更するとエクスポートに不整合が出たり、Dailyのエクスポートが飛んだりする可能性があります。

週の最終日からこの3日ぶんの余裕を取ると、先週の数字が月曜と水曜で食い違う事態を減らせます。

Analytics 360のプロパティなら、Fresh Dailyという選択肢もあります。データは通常午前5時までに届き、その日のうちに更新が数回入ります。360のDailyやFresh Dailyでは、前日分の書き出しが終わったことを知らせる完了シグナルも送られます。標準プロパティでその前提を置けない場合は、実行時刻に余裕を持たせる設計が無難です。

なお、Streamingのevents_intraday_は当日の速報向けです。週次の確定値にはDailyのテーブルを使い、ユーザー帰属のデータはStreamingに頼らない、というのが公式の書き方に沿った使い分けです。

接続する

BigQuery MCPサーバーを追加する

BigQuery MCPサーバーは、Googleがリモートで提供するエンドポイントです。Claude Codeには、HTTPトランスポートで追加します。

claude mcp add --transport http --scope project bigquery https://bigquery.googleapis.com/mcp

--scopeの既定はlocalです(v2.1.289のclaude mcp add --helpではlocal, user, or projectから選びます)。projectにするとレポート用ディレクトリに.mcp.jsonができ、定例スクリプトからも同じ接続設定を使えます。

OAuthクライアントの発行やIAMロールの割り当てなど、事前準備の詳細はClaude BigQuery連携で扱っています。GA4のエクスポート先データセットに対しては、少なくとも次のロールが要ります。

• MCP Tool User(roles/mcp.toolUser)
• BigQuery Job User(roles/bigquery.jobUser)
• BigQuery Data Viewer(roles/bigquery.dataViewer)

BigQuery側の認証はOAuth 2.0で、OAuthクライアントのIDとシークレット、またはエージェントIDを使います。サーバーが動的クライアント登録に対応しない場合、Claude Codeではclaude mcp addの--client-idなどで資格情報を渡します。

追加できたら、Claude Codeの中で/mcpを開いてOAuth認証を済ませ、bigqueryが接続済みになっているかを確認します。

任意: Google Analytics MCPサーバーも足す

APIの側も使いたい場合は、Googleのリポジトリが示すコマンドで登録します。Python 3.10以上とpipxが前提で、Application Default Credentialsにanalytics.readonlyスコープを含める必要があります。

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

事前にGoogle Cloudプロジェクトで、Google Analytics Admin APIとGoogle Analytics Data APIを有効にします。claude mcp addのスコープや--envの扱いはClaude Code MCP設定ガイドが詳しいです。

GA4のスキーマをCLAUDE.mdに書いておく

GA4のイベントテーブルは、1行が1イベントで、パラメータがevent_paramsという繰り返しレコードに入っています。ページURLや売上額を取るにはUNNESTで展開してキーを指定する必要があり、Googleの基本クエリ集もこの形です。

日本語で「先週のPV数」と聞くだけでも、Claudeはテーブル情報を調べてクエリを組み立てられます。それでも毎回の実行でぶれないようにするには、集計の約束事をプロジェクトのCLAUDE.mdに固定しておくのが確実です。次はその一例です。

# GA4レポート作業ルール
 
- 対象データセット: `my-project.analytics_123456789`(自分の環境の名前に置き換える)
- テーブルは `events_*` を使い、日付は必ず `_TABLE_SUFFIX` で絞る
- 当日分の `events_intraday_*` は週次レポートに含めない
- PV は `event_name = 'page_view'` の件数
- ページURLは `event_params` の `key = 'page_location'` を UNNEST して取る
- ユーザー数は `COUNT(DISTINCT user_pseudo_id)`
- 売上は `event_name = 'purchase'` の `event_params` の `value` を合計する
- 集計期間は「直近の完全な月〜日の1週間」。最終日より3日以上前までを対象にする
- 実行するSQLは読み取り専用ツールだけを使う

ここでの要点は3つあります。日付の絞り込みにワイルドカードテーブルの_TABLE_SUFFIXを使うこと、パラメータはUNNESTで取ること、当日のintradayを混ぜないことです。最後の「3日以上前」は、前節のテーブル更新の仕様を踏まえた運用上の決めごとで、公式が示す数字ではありません。

レポートの体裁もCLAUDE.mdで固定する

数字の出し方と同じく、出力の形も毎週そろえておくと、前週のファイルと見比べやすくなります。集計ルールの下に、次のような出力形式を足します。

## レポートの形式
 
1. 冒頭に対象期間(開始日〜終了日)を書く
2. 日別のPV・ユーザー数・購入件数・売上を表にする
3. 前週比は増減の絶対値と%を併記する
4. 変化が大きい指標を3点まで、数字を添えて要約する
5. 集計に使ったテーブルの範囲(`_TABLE_SUFFIX`の値)を末尾に残す

末尾に_TABLE_SUFFIXの範囲を残しておくと、後日「この数字はどの日付範囲か」と聞かれたときに、再実行なしで答えられます。

週次の問い合わせを組み立てる

ルールを置いたうえで、依頼の文面は自然言語のままにします。

先々週(月〜日)のGA4データで、日別のPV数とユニークユーザー数、
purchaseイベントの件数と売上合計を出して。前の週との増減も並べて。

Claudeが組み立てるクエリは、Googleの基本クエリ集にある形に近くなります。例えば購入イベントの合計値を取る部分は、おおよそ次のような形です(公式の例に沿った書き方の一例で、Claudeの実際の出力ではありません)。

SELECT
  event_date,
  COUNT(*) AS purchases,
  SUM((SELECT COALESCE(value.int_value, value.float_value, value.double_value)
       FROM UNNEST(event_params) WHERE key = 'value')) AS revenue
FROM `my-project.analytics_123456789.events_*`
WHERE event_name = 'purchase'
  AND _TABLE_SUFFIX BETWEEN '20260914' AND '20260920'
GROUP BY event_date
ORDER BY event_date

出てきた数字は、初回だけGA4の管理画面の値と突き合わせます。エクスポートは、管理画面のレポートと集計の仕組みが違うため、完全に一致する保証はありません。差分が出る理由はエクスポートのドキュメントに「GA画面との違い」として整理されています。ずれ幅の目安を一度つかんでおくと、定例運用でおかしな値を見つけやすくなります。

claude -pとcronで週次に回す

hooksは「定時起動」の仕組みではない

hooksはツール実行やセッション終了といったイベントに反応する仕組みで、曜日と時刻で起動する機能ではありません。週次の起動はOSのcron(macOSならlaunchd)に任せ、Claude Code側は非対話モードのclaude -pで1回分の作業を担当させます。

hooksが役立つのは、レポートを書き終えたあとの後処理です。生成したファイルの整形や通知は、PostToolUse hookで拾えます。

定例スクリプトの例

-pは、対話なしでプロンプトを実行して結果を標準出力に返します。MCPツールの許可はmcp__<サーバー名>__<ツール名>の形で書きます。BigQuery MCPサーバーのexecute_sql_readonlyは、読み取りだけを許可するツールです。書き込みが可能なexecute_sqlは許可に含めません。

#!/bin/bash
# weekly-ga4-report.sh
cd "$HOME/ga4-report" || exit 1   # CLAUDE.md と .mcp.json を置いたディレクトリ
 
claude -p "先々週(月〜日)のGA4レポートを作って。日別PV、ユーザー数、
purchaseの件数と売上、前週比を表にして、気づいた変化を3点で要約して。" \
  --allowedTools "mcp__bigquery__execute_sql_readonly,\
mcp__bigquery__get_table_info,mcp__bigquery__list_table_ids" \
  --permission-prompts none \
  --output-format json | jq -r '.result' \
  > "reports/ga4-$(date +%Y%m%d).md"

--permission-prompts noneは、スケジュール実行のように承認する人がいない場面のためのフラグで、v2.1.259以降で使えます。v2.1.289の--helpには、次のように載っています。

claude --help | grep -A6 -e "--permission-prompts"

  --permission-prompts <target>         Who answers permission prompts with
                                        --print: "host" (the SDK host or
                                        --permission-prompt-tool) or "none"
                                        (nobody: anything that would prompt is
                                        denied automatically; the permission
                                        mode still decides everything else)

許可していない操作は自動で拒否され、実行は続きます。許可ルールやパーミッションモードが先に判定するので、このフラグが拒否するのは、他で決まらなかった確認だけです。

スクリプト中のパイプには注意点があります。claude -p ... | jqの終了コードは、末尾のコマンド(jq)のものになります。claudeの失敗を拾うには、冒頭にset -o pipefailを足します。cronの実行環境はPATHが短いので、claudeとjqはフルパスで書くと安全です。

cronへの登録は次の1行です。

0 15 * * 1 /bin/bash $HOME/ga4-report/weekly-ga4-report.sh

月曜15時の実行は、日曜までの集計に対して1日程度しか空きません。前節のルールは「最終日から3日以上前」が対象です。そのため依頼文は先週ではなく「先々週(月〜日)」にしています。先週を対象にしたい場合は、実行を水曜以降にずらします。どちらを選ぶかは、レポートを何曜日までに欲しいかで決まります。

無人実行では/mcpパネルが使えず、OAuthの認証をその場で進められません。v2.1.196以降でtool searchが有効な既定の状態では、認証が要るサーバーがあるとClaudeには「認可するまでそのサーバーのツールは使えない」と伝わります。cronに載せる前に、対話セッションの/mcpか、シェルからclaude mcp login bigqueryでサインインを済ませておきます。

-pの細かいオプションはClaude Code -pモードで整理しています。--bareを付けると、CLAUDE.mdの自動読み込みとMCPサーバーの読み込みが止まり、OAuthのログイン情報やキーチェーンも読まれません。この記事の構成は集計ルールをCLAUDE.mdに置いているので、付けるなら--append-system-prompt-fileでルールを、--mcp-configで接続を渡し直します。Anthropicへの認証はANTHROPIC_API_KEYで行います。付けずに動かす場合は、claude -pでも.mcp.jsonのサーバーが接続されます。

つまずきやすいところ

課金と権限の詳細はClaude BigQuery連携にもまとめています。似た構成の週次レポートとしては、Cowork Amplitude自動化がプロダクト分析ツール側の例です。

まとめ

週次レポートの叩き台は、読み取り専用のBigQuery MCPと、集計ルールを書いたCLAUDE.mdがあれば日本語の依頼だけで作れます。

対象週を先週にするか先々週にするかは、レポートを何曜日までに欲しいかで決まります。実行曜日を先に決め、それに合わせて集計期間を置く順番にすると、翌週に数字が食い違いにくくなります。