Google Analytics MCPの導入手順と使い方｜1.0.0の書き込み・HTTP版・認証とクォータ【2026年11月】

Google Analytics MCPサーバーは、GA4のデータをClaude CodeやAntigravity CLIなどのAIクライアントから自然言語で問い合わせるための、Google公式のMCPサーバーです。PyPIで配布されるPythonパッケージ「analytics-mcp」として提供され、Google Analytics Admin APIとData APIを呼び出します。

2026年11月3日公開の1.0.0で「Experimental」の表記が外れ、共有サーバーとして動かすHTTP版とOAuth 2.1の認証が加わりました。その前の0.8.0では、GA4に注釈を書き込むツールも追加されています。この記事では1.0.0を手元で起動して確かめた結果をもとに、導入手順、クライアント別の設定、書き込みとHTTP版の使いどころ、Data APIのクォータを整理します。

まとめ：Google Analytics MCPで押さえる要点

• 最新版はanalytics-mcp 1.0.0（2026年11月3日）。既定のツールは9つで、すべて読み取り用です。
• 起動時に --allow-write を付けると、注釈を作る create_property_annotation が加わり10ツールになります。このとき認証情報には analytics.edit スコープが必要です。
• 準備はAdmin APIとData APIの有効化、analytics.readonly 付きのADC、GA4プロパティへのアクセス権、Python 3.10以上とpipxの4つです。
• 1.0.0の --transport http は、利用者ごとのOAuthトークンで動くマルチテナント向けです。手元のADCは使われないため、コマンドを起動できるクライアントで1人で使うなら従来のstdio版を選びます。
• 通常レポートはData APIのCoreクォータを消費し、リアルタイムレポートと目標到達プロセスは、それぞれRealtime・Funnelの別枠を消費します。上限に先に当たりやすいのは同一プロジェクト・同一プロパティで1時間1万4,000トークンの枠です。
• イベント単位の生データやほかのデータとの結合が必要なら、BigQueryエクスポートとBigQueryのMCPサーバーを組み合わせます。

Google Analytics MCPサーバーの提供形態と1.0.0の変更点

MCP（Model Context Protocol）は、AIアプリケーションが外部のツールやデータにアクセスするための共通規格です。規格の仕組みはMCP（Model Context Protocol）とは？仕組み・APIとの違い・MCPサーバーの作り方で扱っています。Google Analytics MCPサーバーはGA4のAPIをMCPで公開するサーバーで、リポジトリはgoogleanalytics/google-analytics-mcp（Apache-2.0）です。

公式告知は2025年7月、PyPIへの初回公開は2025年8月22日の0.1.0でした。1.0.0のリリースノートには「graduate from experimental」とあり、READMEの見出しからもExperimentalの表記が消えています。一方、Google for Developersの紹介ページは、2026年11月6日に確認した時点でも読み取り専用のツールとして説明しています。0.8.0以降の書き込み機能は、GitHubのREADMEとリリースノートで確認してください。

1.0.0の依存は mcp>=2.3.0,<3 と google-adk>=2.11.0 で、0.7.0から大きく上がっています。0.7.0で動かしていた環境は、更新後に /mcp などでツール一覧を取り直してください。社内で使う場合は版を固定し、更新のたびにツールの増減を確認する運用が安全です。

ツール一覧：既定の9つと--allow-writeで増える1つ

1.0.0をstdioで起動し、MCPの tools/list を取得すると9ツールが返りました。--allow-write を付けて起動し直すと10ツールになります。0.8.0から各ツールにMCPのツール注釈が付き、読み取り用は readOnlyHint: true、注釈の作成は readOnlyHint: false です。

GitHubのmainブランチのREADMEには、list_key_events・create_custom_dimension・create_key_event も載っています。ただし1.0.0のタグのREADMEとPyPIのパッケージにはこの3つが無く、1.0.0を起動しても一覧に出ません。mainブランチのREADMEだけを見て設定を組まないよう注意してください。

集計で迷いやすいのは run_report と run_conversions_report です。後者のツール説明は、コンバージョン、広告の成果、ROAS、アトリビューションモデル（DATA_DRIVEN または LAST_CLICK）を扱うときはこちらを使うよう指示しています。

導入手順：API有効化から認証情報の作成まで

Google CloudでのAdmin API・Data APIの有効化

Google Cloudのプロジェクトで「Google Analytics Admin API」と「Google Analytics Data API」の2つを有効にします。gcloudなら次のコマンドです。

gcloud services enable analyticsadmin.googleapis.com analyticsdata.googleapis.com --project=YOUR_PROJECT_ID

Admin APIを有効にし忘れると、get_account_summaries などの管理系ツールは「403 Google Analytics Admin API has not been used in project … SERVICE_DISABLED」で失敗します。run_report は動くので、プロパティ一覧だけ取れない状態になります。0.7.0ではこのエラーが通常の応答として返っていましたが、1.0.0で同じ条件を試すと isError: true の失敗として返りました。クライアントの画面にツールの失敗が表示されるようになったため、原因に気付きやすくなっています。

ADCの作成：ユーザー認証とサービスアカウント

stdio版はApplication Default Credentials（ADC）で認証し、既定では https://www.googleapis.com/auth/analytics.readonly スコープを要求します。自分のGoogleアカウントで認証する場合は、OAuthクライアント（デスクトップまたはウェブ）のJSONをダウンロードしてから、READMEにある次のコマンドを実行します。

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

完了時に表示される「Credentials saved to file: […]」のパスを、クライアント設定の GOOGLE_APPLICATION_CREDENTIALS に書きます。

サービスアカウントを使う場合は、そのメールアドレスをGA4の［管理］→［プロパティのアクセス管理］で「閲覧者」として追加します。GA4側の権限を付け忘れると、APIを有効にしていてもプロパティが一覧に出ません。鍵ファイル（JSON）を GOOGLE_APPLICATION_CREDENTIALS で直接渡す構成でも、1.0.0の run_report は結果を返しました。ただし鍵は漏れたときの影響が大きいため、組織のポリシーで鍵の発行が禁止されていれば、ユーザー認証かREADMEにある権限借用（--impersonate-service-account）を選びます。

Python 3.10以上とpipxによる起動確認

1.0.0の Requires-Python は3.10以上です。macOSの /usr/bin/python3 はCommand Line Tools付属の古い版であることが多いため、python3 --version で確認してください。READMEはpipxでの起動を前提にしています。版を固定するなら、pipxは --spec、uvは uvx の @ 指定を使います。

# pipx（READMEの方式）で版を固定する
pipx run --spec analytics-mcp==1.0.0 analytics-mcp

# uv を使う場合
uvx [email protected]

起動後にプロンプトが返らないのは、標準入力からのMCPメッセージを待っているためで、正常な動作です。

Claude Code・Antigravity CLI・Claude Desktopへの登録設定

Claude Codeの登録コマンド

READMEの手順に版の固定を加えた例です。--scope user を付けると ~/.claude.json に保存され、すべてのプロジェクトから使えます。チームで共有したい場合の --scope project はプロジェクト直下の .mcp.json に書かれるため、認証ファイルのパスを含めないよう注意してください。

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

Claude Codeで /mcp を開き、analytics-mcp が接続済みになっていれば完了です。0.8.0までのREADMEの設定例にあった GOOGLE_PROJECT_ID は表記の誤りで、1.0.0で GOOGLE_CLOUD_PROJECT に直りました。古い記事の設定例を写した場合は書き換えてください。Claude Code側の権限設定はClaude Codeの使い方｜インストールから権限・CLAUDE.md設定、初日の進め方までで整理しています。

Antigravity CLIの設定とGemini CLIからの移行

GitHubのREADMEは今もGemini CLIを最初の接続先にしていますが、Google for Developersの紹介ページは「Gemini CLI は非推奨」と注記し、Antigravity CLIとAntigravity IDEの手順に置き換えています。設定先は ~/.gemini/config/mcp_config.json（ワークスペース単位なら .agents/mcp_config.json）で、書式は次のとおりです。

{
  "mcpServers": {
    "analytics-mcp": {
      "command": "pipx",
      "args": ["run", "--spec", "analytics-mcp==1.0.0", "analytics-mcp"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON",
        "GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID"
      }
    }
  }
}

Antigravity CLIなら agy を起動して /mcp と入力し、一覧に analytics-mcp が出れば接続できています。Gemini CLIの ~/.gemini/settings.json にも同じ mcpServers の形式で書けますが、Gemini CLIは2026年6月18日に、無料の個人向けログインとGoogle AI Pro・Ultra経由のリクエスト処理を終えています。Googleの移行告知が継続利用の経路として挙げているのは、有料のGemini APIキーなどです。条件と移行手順はGemini CLIは終了した？個人向け停止後も使える条件とAntigravity CLIとの違い・移行手順で解説しています。

Claude Desktopの設定ファイル

Claude Desktopは、macOSなら ~/Library/Application Support/Claude/claude_desktop_config.json、Windowsなら %APPDATA%\Claude\claude_desktop_config.json の mcpServers に、上と同じ形式（command・args・env）で書きます。Issue #40では、Data API系のツールが結果を返さない例に対し、メンテナーが「GOOGLE_APPLICATION_CREDENTIALS に認証ファイルのフルパスを書き、設定後はアプリを完全に終了してから再起動する」よう案内しています。

起動と認証のエラーの対処

公式ページのトラブルシューティングと、GitHubのIssueで報告されている代表的なエラーです。

多くのMCPクライアントは設定ファイル内の ~ や $HOME を展開しないため、パスは /Users/username/… のように書きます。pipx の絶対パスは which pipx で調べられます。割り当てプロジェクトは、環境変数の代わりに gcloud auth application-default set-quota-project YOUR_PROJECT_ID でADCファイルに書き込んでもかまいません。

名前解決のエラーは、Claude Code利用者からIssue #179として報告されていたものです。2026年11月3日にmainブランチへ追加されたTROUBLESHOOTING.mdは、macOSでVPNやスプリットDNSを使うとgrpcioのc-aresリゾルバーが失敗すると説明し、GRPC_DNS_RESOLVER=native を任意の回避策として挙げています。Claude Codeなら claude mcp add に -e "GRPC_DNS_RESOLVER=native" を足し、同じエラーが出たときだけ付けます。

書き込みツールの有効化：--allow-writeと注釈の作成

0.8.0から、--allow-write を付けて起動したときだけ書き込み用のツールが登録されます。1.0.0で使えるのは、GA4のレポートに日付付きのメモを残す create_property_annotation の1つです。リリース日やキャンペーン開始日をAIに記録させておけば、後で「この日からセッションが減った理由」を尋ねたとき、list_property_annotations から施策の記録を拾えます。

書き込みには、次の3つがすべて必要です。

• 起動引数に --allow-write（環境変数なら ANALYTICS_MCP_ALLOW_WRITE）を付ける
• ADCを analytics.edit スコープ付きで作り直す（--scopes に analytics.readonly・analytics.edit・cloud-platform の3つを並べる）
• GA4プロパティで注釈を作成できるロールを持つ（GA4の注釈のヘルプはアナリスト以上と説明し、1.0.0のエラーヒントはマーケティング担当者または編集者と案内しています）

権限が足りずに失敗した場合、1.0.0はエラーに上の条件と再認証コマンドを書いたヒントを付けて返します。注釈のタイトルは60文字まで、説明は150文字まで、色はPURPLE・BROWN・BLUE・GREEN・RED・CYANから選びます（ORANGEはGA4の自動注釈用）。

書き込みを有効にするかは、AIに渡す権限の問題として判断します。注釈は消しても集計に影響しませんが、mainブランチで準備中のカスタムディメンションやキーイベントの作成は、プロパティの設定そのものを変えます。共有の本番プロパティでは、読み取り用のサーバーと書き込み用のサーバーを別名で登録し、書き込み側は必要な人の環境と検証用プロパティに限定する運用が現実的です。チーム共有の .mcp.json に書き込み版を入れるのは避けてください。

HTTP版のホスティング：マルチテナントとOAuth 2.1

1.0.0では --transport http を付けると、Streamable HTTPのMCPサーバーとして起動します。チームで1つのサーバーを共有し、利用者がそれぞれ自分のGoogleアカウントでGA4にアクセスする構成のための機能です。

pipx run --spec analytics-mcp==1.0.0 analytics-mcp \
  --transport http --stateless-http --host 0.0.0.0 --port 8080

stdio版との大きな違いは、サーバー側のADCを使わないことです。手元で --stateless-http 付きで起動し、Authorization ヘッダーなしで /mcp に run_report を送ると、「Missing OAuth access token. Provide an 'Authorization: Bearer <token>' header or enable OAuth on the server.」というエラーが返りました。ツールを呼ぶたびに、利用者のOAuthアクセストークンが必要になります。

トークンの受け渡し方は2通りです。

• 上流のエージェントが渡す：Google ADKなどのエージェント側でユーザーごとのOAuthを設定し、Bearerトークンを転送します。状態を持たないので、Cloud Runで複数インスタンスに広げられます。
• サーバー自身が認可サーバーになる（--oauth）：GOOGLE_OAUTH_CLIENT_ID と GOOGLE_OAUTH_CLIENT_SECRET を設定すると、MCPのOAuth 2.1認可サーバーが有効になります。公開URLで運用する場合は、ANALYTICS_MCP_ISSUER_URL または --issuer-url に、その公開ベースURLも指定します。READMEの注記によると、クライアント登録やリフレッシュトークンはプロセスのメモリに置かれ、再起動すると再認証が必要です。Cloud Runの例も --max-instances 1 で1台に固定しています。

1人でローカルのコマンドを起動できるクライアントを使うなら、通常はstdio版で足ります。HTTP版が向いているのは、社内の複数人に同じ接続先を配りたい場合や、ローカルのコマンドを起動できないクライアントから使いたい場合です。後者では、クライアントがリモートMCPサーバーとOAuthに対応しているかを先に確認します。公開する前に、Cloud Run側の認証、OAuthクライアントのリダイレクトURI（/oauth/callback）、シークレットの保管場所を決めておく必要があります。

自然言語で聞ける分析と聞けない分析

READMEのサンプルは「過去180日で多いイベント」「直近6か月のユーザーはログイン済みが多いか」などです。AIはこうした質問を、Data APIのディメンションと指標の名前（sessionSource・eventCount など）に置き換えて run_report を呼び出します。最初にプロパティIDを伝え、期間を「2026年10月1日から31日」のように日付で指定すると、AIの探索と集計のやり直しが減ります。

次のような分析はできません。

• イベント単位・ユーザー単位の生データ：Data APIは集計結果を返すAPIです。ユーザーごとの行動を1行ずつたどるには、BigQueryエクスポートが必要です。
• 探索レポートと同等の分析：経路データ探索やセグメントの重なりは、ツールとして公開されていません。探索の手法ごとの違いはGA4のデータ探索ツール（探索レポート）｜7手法の使い分け・設定例・公式の上限値を参照してください。

Data APIのクォータとトークン消費

MCPサーバー経由の集計も、通常のData APIと同じクォータを消費します。公式の「Data API limits and quotas」（2026年10月26日更新）に載っているCoreクォータの値は次のとおりです。

run_report などに return_property_quota: true を渡すと、応答に消費量と残量が入ります。1.0.0で日付別セッション数を集計し、総行数7件に対して取得上限を3件にしたリクエストの結果は、1日の枠が「消費1・残り199,979」、1時間の枠が「残り39,995」、プロジェクト×プロパティの枠が「残り13,999」でした。標準プロパティの値と一致しています。

上限に先に当たりやすいのは、プロジェクト×プロパティあたり1時間14,000トークンの枠です。サーバーエラーの枠を使い切ると、そのプロジェクトからプロパティへのリクエストがすべて止まります。公式のクォータ管理の説明では、期間を28日から365日に延ばすと消費が約3倍になる場合があるとされています。AIには必要なディメンションと期間だけを指定させ、条件を少しずつ変えた集計を繰り返させないことです。

数値がGA4の管理画面と合わない原因

AIが答えた数字が管理画面と食い違う場合は、まず期間・ディメンション・指標・フィルタが同じかを確認します。条件が同じなのに値が違うときは、run_report の応答に含まれる metadata を見ると原因を絞り込めます。

アクティブユーザー数やセッション数などのユニーク数は、Data APIではHyperLogLog++による推定値です。サンプリングされていない集計でも、全件を厳密に数えた値とは限りません。しきい値は、年齢・性別などのユーザー属性や、それらに基づくオーディエンスを含む集計などで、個人の特定を防ぐために適用される場合があります。しきい値の対象になりうるリクエストには1時間120件の枠もあり、今回の応答にも「potentially_thresholded_requests_per_hour」として残量が返ってきました。

管理画面と合わせたいときは、AIへの指示に「metadataの subject_to_thresholding と data_loss_from_other_row も報告して」と書いておくと、食い違いの理由まで一緒に返ってきます。

権限設計とデータの取り扱い

既定の起動では analytics.readonly スコープしか要求しないため、GA4の設定は変わりません。ただし、読み取り専用であることと、データが外部に出ないことは別の話です。集計結果はツールの応答としてAIのコンテキストに入り、利用しているAIサービスへ送られます。

• 認証に使うアカウントには、必要なプロパティだけに「閲覧者」を付けます。閲覧者でも収益や費用のデータは見えるため、渡したくない場合はGA4の「データの制限」（収益指標・費用指標）を設定したロールを割り当てます。応答の schema_restriction_response には、実際に適用された制限が返ります。
• AIサービス側の学習利用や保存期間は、法人向けの契約条件を確認してから使います。認証情報のJSONはリポジトリに入れず、設定ファイルにはパスだけを書きます。

公式版を選ばない場面：BigQuery経由とサードパーティー製

Google Cloudは、BigQueryなどのGoogleサービス向けにGoogleが運営するリモートMCPサーバーを提供しています。対応製品の一覧（2026年11月2日更新）にGoogle Analyticsは含まれていません。1.0.0のHTTP版はあくまで自分でホストするもので、URLを登録するだけで使える公式のリモート版ではありません。

ホスト型のGA4 MCPを提供するサードパーティー製品もありますが、GA4のデータと認証の権限を第三者のサーバーに預けることになります。複数人で共有する場合は、OAuth設定やシークレット管理、サーバー運用を自社で担えるなら、1.0.0のHTTP版をCloud Runで動かす構成が候補になります。

判断が分かれるのは分析の粒度です。日次やチャネル別の集計で足りるなら公式版で十分です。ユーザー単位の行動分析や、広告・CRMのデータとの結合が必要なら、GA4のBigQueryエクスポートを設定し、BigQueryのリモートMCPサーバーからSQLで問い合わせます。BigQuery側のツールと権限の分け方はBigQuery MCPサーバーの接続手順｜6ツールの権限分離とスキャン量の制御設計、エクスポートされたGA4のネストした列の扱いはBigQuery UNNESTの書き方：ARRAYとSTRUCTの展開とGA4スキーマ・JSON型の取り出しで解説しています。どちらの構成でも、AIに答えさせる前に「どの指標で何を判断するか」を決めておかないと、数字の羅列で終わります。計測設計から相談したい場合は、Webコンサルティング・アクセス解析で支援しています。

よくある質問

Google Analytics MCPは無料で使えますか？

analytics-mcp自体はApache-2.0のオープンソースで、Data APIの利用にも料金はかかりません（クォータはあります）。AIクライアントの料金と、HTTP版をCloud Runでホストする場合の利用料は別にかかります。

Claude CodeやClaude DesktopでもGoogle Analytics MCPを使えますか？

使えます。Claude Codeは claude mcp add、Claude Desktopは claude_desktop_config.json で登録し、認証ファイルは絶対パスで指定します。

GA4のMCPサーバーでGA4の設定を変更できますか？

既定では変更できません。--allow-write を付けて起動し、analytics.edit スコープと注釈を作成できるロール（公式ヘルプではアナリスト以上）を用意すると、1.0.0では注釈の作成だけができます。キーイベントやカスタムディメンションの作成は、2026年11月6日時点でPyPIの版に入っていません。

ChatGPTからGoogle Analytics MCPを使えますか？

手元のコマンドを起動できないクライアントからは、stdio版は使えません。1.0.0のHTTP版を公開URLでホストし、--oauth などで利用者の認証を付ければ、リモートMCPサーバーを登録できるクライアントから接続する経路はできます。ChatGPT側で登録できる条件は、OpenAIのヘルプで確認してください。

旧ユニバーサルアナリティクス（UA）のデータも取得できますか？

取得できません。対象はGA4のプロパティだけで、ユニバーサルアナリティクスは2024年7月1日から順次、APIを含めて利用できなくなっています。GA4の仕組みはGA4とは？仕組みとUAとの違い・導入と運用体制の判断まで解説で解説しています。

関連記事

• MCP（Model Context Protocol）とは？仕組み・APIとの違い・MCPサーバーの作り方
• BigQuery MCPサーバーの接続手順｜6ツールの権限分離とスキャン量の制御設計
• Firebase MCPサーバーとは｜ツール群の絞り込みと本番接続の判断【2026年8月時点】
• GA4とは？仕組みとUAとの違い・導入と運用体制の判断まで解説
• Gemini CLIは終了した？個人向け停止後も使える条件とAntigravity CLIとの違い・移行手順