Claude CodeにGA4のMCPサーバーを繋ぐ手順 — Google Analyticsを自然言語で分析

Claude CodeでGoogle Analytics(GA4)を使うには、Google公式のAnalytics MCPサーバー(analytics-mcp)を登録します。必要なのは、pipx の用意、2つのAPI(Admin API / Data API)の有効化、読み取り専用スコープでのADC認証、claude mcp add 1本での登録の4つです。

GoogleはGoogle Analytics向けのMCP(Model Context Protocol)サーバーを、GitHubのリポジトリ googleanalytics/google-analytics-mcp で公開しています。GA4のデータを、管理画面ではなくClaude Codeとの会話で問い合わせられるようになります。Google自身の説明は「GeminiのようなLLMにAnalyticsのデータをつなぐ」ですが、MCPに対応したクライアントなら同じサーバーを使えます。リポジトリにはClaude Code用の登録コマンドも載っています。実験管理ならW&BのMCPサーバーも同じ要領で繋げます。

このサーバーは、自分のマシンで動くローカルサーバーです。BigQueryにエクスポートしていない標準のGA4プロパティでも動きます。SQLは要らず、Google Analytics Data APIの上に載っています。離脱の理由をクリックやスクロールから探るなら、ClaudeとMicrosoft Clarityの連携も併用できます。取得する前のイベント設計はGA4の計測設計書の作り方にまとめています。

Analytics MCPサーバーでできること

サーバーはGoogle Analytics Admin APIとData APIを使い、次の7つのツールを提供します。

Googleのドキュメントは、このサーバーを「読み取り要求のみ」と説明しています。Google Analyticsの構成や設定を編集する機能はありません。書き込み系のツールが並んでいないのは、この説明どおりです。

リポジトリのタイトルには「Experimental」と付いています。ツール名やパラメータが今後変わる可能性があるものとして扱っておくのが無難です。

前提: 登録の前に揃える3つ

READMEが求める準備は、Pythonの実行環境、Google Cloudプロジェクトでの設定、認証情報の3つです。

認証: ADCとreadonlyスコープ

認証はApplication Default Credentials(ADC)で行います。READMEの条件は2つです。

• 認証情報は、対象のGoogle Analyticsアカウントまたはプロパティにアクセスできるユーザーのものであること
• スコープに https://www.googleapis.com/auth/analytics.readonly を含めること

READMEはgcloudコマンドの例を2通り示しています。どちらを選ぶかは、自分のGoogleアカウントで入るか、サービスアカウントを借りるかです。

1つ目のコマンドです。

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

2つ目のコマンドです。

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

どちらも、完了時に次の形で認証情報ファイルのパスが表示されます。このパスを次の登録手順で使うので、控えておきます。

Credentials saved to file: [PATH_TO_CREDENTIALS_JSON]

Claude Codeに登録する

READMEのClaude Code向け手順は、claude mcp add を1本実行するだけです。

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

PATH_TO_CREDENTIALS_JSON は前節で控えたパス、YOUR_PROJECT_ID はAPIを有効にしたGoogle CloudプロジェクトのIDに置き換えます。

-- より後ろがサーバーを起動するコマンド本体です。Claude Codeの公式ドキュメントでは、stdioサーバーではこの -- でClaude側のオプション(--env、--scope など)とサーバーへの引数を分けると説明されています。

--env(-e)は、サーバー名の後ろ、-- の前に置きます。名前を -e の直後に置くと、名前が環境変数のペアとして読まれて拒否されます。次のエラーになります。

Invalid environment variable format: analytics-mcp, environment variables should be added as: -e KEY1=value1 -e KEY2=value2

READMEの例は analytics-mcp を先に書いて、その後ろに --scope と -e を並べているので、この問題は起きません。成功すると、保存先を示す2行が出ます(--scope user の場合)。

Added stdio MCP server analytics-mcp with command: pipx run analytics-mcp to user config
File modified: ~/.claude.json

スコープの選び方

READMEの例は --scope user で、登録するとすべてのプロジェクトからGA4のMCPサーバーが見えます。Claude Codeには3つのスコープがあります。

認証情報ファイルのパスは自分のマシン固有の値なので、.mcp.json にそのまま書いてチームで共有するには向きません。個人でGA4を見る用途なら、READMEどおりuserかlocalで足ります。

projectスコープにするなら、パスを環境変数の参照にします。.mcp.json の env は ${VAR} の展開に対応していて、未設定の変数があるとClaude Codeが警告を出します。--scope project で追加すると、次のファイルができます(値はダミーです)。

{
  "mcpServers": {
    "analytics-mcp": {
      "type": "stdio",
      "command": "pipx",
      "args": ["run", "analytics-mcp"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/credentials.json",
        "GOOGLE_PROJECT_ID": "my-project"
      }
    }
  }
}

共有する前に、2つの値を "${GA_MCP_CREDENTIALS}" と "${GA_MCP_PROJECT_ID}" のような参照に書き換えると、各自の環境変数で値を持てます。

projectスコープには、もう1つ待ち受けがあります。.mcp.json のサーバーは承認するまで接続されず、claude mcp list は次のように表示します。

analytics-mcp: pipx run analytics-mcp - ⏸ Pending approval (run `claude` to approve)

承認は claude を対話で起動して行います。承認前は接続の試行すらされないので、この状態の Pending approval を接続失敗と取り違えないようにします。v2.1.196以降は、信頼前のフォルダでリポジトリにコミットした enabledMcpjsonServers などの承認設定が無視され、サーバーは ⏸ Pending approval のままです。

つながったかを確認する

登録できたかは、次のコマンドで確認できます。Claude Codeを起動している場合は、セッション内の /mcp でも見られます。

claude mcp list
claude mcp get analytics-mcp

一覧に analytics-mcp が出て、状態が ✔ Connected ならつながっています。pipx が無い環境では次の出力になります。

analytics-mcp: pipx run analytics-mcp - ✘ Failed to connect — ENOENT: Executable not found in $PATH: "pipx"

localスコープで登録した場合、claude mcp get は同じ失敗の詳細を次の形で出します。

analytics-mcp:
  Scope: Local config (private to you in this project)
  Status: ✘ Failed to connect
  Issue: ENOENT: Executable not found in $PATH: "pipx"
  Type: stdio
  Command: pipx
  Args: run analytics-mcp
  Environment:
    GOOGLE_PROJECT_ID=my-project

ENOENT は、pipx という実行ファイルが PATH に見つからないという意味です。Environment には登録した環境変数の名前と値が並ぶので、画面を共有するときは認証情報のパスが映らないよう気をつけます。pipx が見つかっているのに失敗する場合は、後の節の症状別の表で切り分けます。

Claude Desktopで使う場合

READMEにClaude Desktop向けの手順はありません。ただしClaude Desktopは claude_desktop_config.json の mcpServers にサーバーを書く方式で、要素は command / args / env です。READMEのGemini向け設定例と同じ形なので、同じ内容を移せます。

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

これは、READMEのGemini向け設定を土台にした書き方の例です。READMEがClaude Desktopでの動作を案内しているわけではありません。ファイルの置き場所や反映手順はClaude Desktop MCP設定ガイドにまとめています。

環境変数の名前にはひとつ注意点があります。READMEの本文は「GOOGLE_CLOUD_PROJECT をenvに足すことを推奨」と書く一方、サンプルのJSONと claude mcp add の例は GOOGLE_PROJECT_ID を使っています。サンプルはどちらも GOOGLE_PROJECT_ID に統一されているので、まずはサンプルどおりに書くのが確実です。

問い合わせの例

登録後は、Claude Codeに自然文で聞くだけです。READMEとGoogleのドキュメントが挙げている質問は次のとおりです。

• what can the analytics-mcp server do?(サーバーで何ができるか)
• Give me details about my Google Analytics property with 'xyz' in the name(名前にxyzを含むプロパティの詳細)
• what are the most popular events in my Google Analytics property in the last 180 days?(直近180日でよく発生したイベント)
• were most of my users in the last 6 months logged in?(直近6か月のユーザーの多くはログイン済みか)
• what are the custom dimensions and custom metrics in my property?(プロパティのカスタムディメンションとカスタム指標)
• How many users did I have yesterday?(昨日のユーザー数)
• What were my top selling products yesterday?(昨日売れた商品の上位)

READMEの例はGemini向けですが、質問の中身はMCPクライアントに依存しません。プロパティの特定にはアカウント情報系のツール、集計にはレポート系のツールが使われます。

質問の書き方で結果が安定する

ここからは、Claude Code側で工夫できる部分です。レポート系のツールは、期間・ディメンション・指標を指定して呼び出します。曖昧な聞き方をすると、Claudeが期間や指標を自分で補います。

例えば次のように聞きます。

プロパティ「my-site」の 2026-08-01 から 2026-08-31 について、
ページ別のセッション数の上位10件を出して。
run_report でどのディメンションと指標を使ったかも書いて。

最後の一行が肝です。Claudeが実際に指定したディメンションと指標を答えに書かせると、数字の意味を後から確かめられます。管理画面の値と突き合わせる際にも、条件が揃っているかを確認できます。

CLAUDE.mdに前提を置く

毎回プロパティ名や期間の書き方を伝えるのは手間です。GA4の分析を繰り返すプロジェクトなら、CLAUDE.md に前提を書いておくと、質問が短くなります。次はその一例で、公式の記述ではなく運用上の書き方の案です。

## GA4の問い合わせ規約
- 分析対象は analytics-mcp のプロパティ「my-site」
- 期間は必ず日付で指定し、比較するときは同じ長さの前期間と並べる
- 数字を答えるときは、使ったディメンションと指標を併記する
- 設定変更が必要な提案は、実行せず手順だけを示す

最後の一行は、サーバー自体が読み取り専用でも、GA4の設定変更を提案されたときに、手順として受け取る運用にしておくためのものです。

出力が大きいときの上限

レポートが長い行数を返すと、Claude Codeの側で出力に制限がかかります。Claude Codeは、MCPツールの出力が10,000トークンを超えると警告を出し、既定では25,000トークンで出力を打ち切ります。上限を上げたいときは、環境変数 MAX_MCP_OUTPUT_TOKENS を設定します(警告のしきい値は固定です)。

MAX_MCP_OUTPUT_TOKENS=50000 claude

とはいえ、上限を上げるより、条件を絞ったレポートを複数回に分けて取るほうが扱いやすくなります。ページ別・流入元別など、ディメンションごとに質問を分けます。

つまずきやすい点: 症状から探す

READMEが求める前提条件から外れたときの症状と、リポジトリのissueに報告されている症状を並べます。

mcp SDK 2.0.0との非互換

2026年7月28日にPythonの mcp SDKが2.0.0を公開し、Tool.inputSchema が Tool.input_schema に改名されました。analytics-mcp が上限なしで依存していたため、新規インストールが起動時に上のAttributeErrorで落ちました(リポジトリのissue #199)。修正は翌日(2026年7月29日)公開のv0.7.0で入り、PyPIの依存関係は mcp<2,>=1.24.0 になっています。古い環境で起動に失敗するときは、uvx --with "mcp<2" analytics-mcp のように mcp を1系に固定する回避策がissueのコメントで共有されています。

macOSでのDNS解決エラー

macOSでClaude Codeからツールを呼ぶと、DNS解決に失敗する報告があります(issue #179。openのままのissueです)。報告者の原因分析は、gRPCのc-ares DNSリゾルバーがClaude Codeの子プロセスから名前を引けないことです。報告者が示す回避策は、環境変数 GRPC_DNS_RESOLVER=native をサーバーの env に足すことです。

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

この環境変数はGoogleの公式手順には含まれません。同じ症状が出たときの試し方の1つです。

WindowsでのADC使用時のハング

Windows 11で、ユーザー認証情報のADCを使うと、initialize と tools/list は通るのに get_account_summaries などのツール呼び出しが応答しない報告がありました(issue #134、#156。どちらもclosed)。#134にはサービスアカウントのJSONキーに替えると動いたという報告があり、#156には「v0.6.0で解消するはず」というコメントが付いています。古いバージョンで同じ症状が出たら、バージョンを疑います。

ほかのGoogle系MCPサーバーとの違い

BigQueryにGA4のデータをエクスポートしている場合は、Claude BigQuery連携のように、SQLで生データを扱う道もあります。今回のAnalytics MCPサーバーは、SQLもBigQueryも不要で、Data APIのレポートを単位に問い合わせる点が違います。標準のGA4プロパティだけで始められるのが入口の軽さです。

Google Cloud全般の操作はgcloud MCPサーバー、権限の絞り込みはGoogle CloudのMCPサーバーをIAMで権限制御するが扱っています。MCPそのものの仕組みはMCPとはを参照してください。

まとめ

個人で見るなら、READMEどおりuserスコープで足ります。チームで共有するときだけ、projectスコープの ${VAR} 参照と承認手順を設計に入れます。