Tag Pilot GA4

Tag Pilot GA4 MCP

読み取り専用の無料のModel Context Protocolサーバーです。 Google Analytics 4に対応しています。Claude、Cursor、または任意の MCP クライアントから、GA4 データについて質問できます。レポート、ファネル、リアルタイムデータ、プロパティの設定、Tag Pilot によるトラッキングの健全性チェックに対応しています。

Google Cloud の設定も、コピーする API キーも必要ありません。 GCP プロジェクト、OAuth クライアント、サービスアカウント、gcloud は不要です。サーバーを追加して GA4 について質問し、ブラウザーで一度承認するだけです。

claude mcp add ga4 -- npx -y @tagpilot/ga4-mcp

はじめる

1. AI クライアントにインストールします（下記参照）。設定は不要です。
2. *「自分が持っている GA4 プロパティはどれですか？」*などと質問します。初回はブラウザーウィンドウが開くか、AI にリンクと ABCD-1234 のようなコードが表示されます。
   • 無料のTag Pilotアカウントにサインインするか、新規作成します。
   • コードが一致することを確認し、このコンピューターを承認します。
   • GA4 プロパティを閲覧できる Google アカウントでサインインし、*「Google アナリティクスのデータの表示とダウンロード」*を許可します。
3. もう一度質問します。接続が完了すると、GA4 MCP ページの接続済みデバイスにコンピューターが表示されます。

インストール

クライアント	方法
Claude Desktop	拡張機能をダウンロードして開きます（Node.js は不要です）
Claude Code	claude mcp add ga4 -- npx -y @tagpilot/ga4-mcp
Cursor	Cursor に追加、または下記の mcp.json を使用します
VS Code	VS Code にインストール
Gemini CLI	gemini extensions install https://github.com/tagpilot/ga4-mcp
その他	npx -y @tagpilot/ga4-mcp（stdio）

Claude Desktop 拡張機能以外はすべて npx で npm パッケージを実行するため、Node.js 18 以降が必要です。このサーバーはMCP Registryにも io.github.tagpilot/ga4-mcp として登録されています。

Claude Desktop

tagpilot-ga4-mcp.mcpbをダウンロードしてダブルクリックするか、設定 → 拡張機能にドラッグし、インストールをクリックして有効にします。任意の API キー欄は空のままにしてください。この拡張機能にはサーバーが同梱されており、Claude Desktop に組み込まれている Node.js で実行されます。

設定ファイルを使う場合は、claude_desktop_config.json（設定 → 開発者 → 設定を編集）に次を追加します。

{
  "mcpServers": {
    "ga4": {
      "command": "npx",
      "args": ["-y", "@tagpilot/ga4-mcp"]
    }
  }
}

Claude Code

claude mcp add ga4 -- npx -y @tagpilot/ga4-mcp

Cursor

Cursor に追加を使用するか、~/.cursor/mcp.json（またはプロジェクト内の .cursor/mcp.json）に追加します。

{
  "mcpServers": {
    "ga4": {
      "command": "npx",
      "args": ["-y", "@tagpilot/ga4-mcp"]
    }
  }
}

VS Code

VS Code にインストールを使用するか、MCP: Add Server → *Command (stdio)*を実行し、npx -y @tagpilot/ga4-mcpを指定します。

Gemini CLI

gemini extensions install https://github.com/tagpilot/ga4-mcp

その他のクライアント（Windsurf、Zed など）でも、同じ command と args を使用します。

ヘッドレス環境と CI：代わりに API キーを使用

ブラウザーで承認できる人がいない場合は、 GA4 MCP ページでキーを作成し、サーバーの 環境変数に TAGPILOT_API_KEY=tpk_… を設定します（例：claude mcp add ga4 --env TAGPILOT_API_KEY=tpk_... -- npx -y @tagpilot/ga4-mcp）。 キーを使うと、デバイス接続はスキップされ、Google サインインのリンクのみが表示されます。

接続の仕組みと Tag Pilot が確認する情報

your machine                              Tag Pilot                          Google
──────────────────────────────────────   ───────────────────────────       ──────────────────────
ga4-mcp makes a PKCE verifier       ──►  POST /v3/public/ga4/device
(it never leaves your machine)           returns a link + code ABCD-1234
any browser, any device: app.tagpilot.io/connect: log in, check the code, approve
  → creates a ga4:mcp key for this device → Google consent (read-only) ─►  accounts.google.com
                                         …/ga4/oauth/callback  ◄──────  one-time code
ga4-mcp polls for the result        ──►  POST /v3/public/ga4/device/token
                                         returns the device key + code
ga4-mcp exchanges code + verifier   ──►  POST …/ga4/oauth/token  ──►    oauth2.googleapis.com
device key + Google tokens saved in ~/.config/tagpilot/ga4-mcp/device.json (mode 600)
GA4 API calls  ─────────────────────────────────────────────────────►  analytics*.googleapis.com

どのブラウザーからでも動作します。gh auth login と同様に、お使いのマシンで待ち受けるものはないため、SSH、コンテナー、WSL、リモート開発マシンからも利用できます。ブラウザーを使える場所（スマートフォンでも可）でリンクを開いて承認すると、サーバーは数秒以内にそれを検知します。

• GA4 データは、お使いのマシンから Google に直接送信されます。 レポート、プロパティ設定、その他ツールが読み取る情報が Tag Pilot を経由することはありません。
• Tag Pilot はトークン交換を仲介するだけです。 Tag Pilot の API は、Tag Pilot の Google OAuth クライアント認証情報を Google のトークンエンドポイントに追加し、Google からの応答を返します。Google のトークンは保存せず、ログにも記録しません。保持するのは、Google のコールバックから受け取る一度限りのサインインコードのみです。お使いのマシンが取得するまで最長 10 分間保持されます。このコードは、お使いのマシンに保持される PKCE 検証子がなければ使えません。記録するのは、交換が行われたことと、どのデバイスで行われたか（GA4 MCP ページの「最終使用日時」）だけです。
• 読み取り専用です。 要求する Google スコープは analytics.readonly のみです。どのツールも GA4 の内容を変更できません。
• 認証情報はお使いのマシンに保存されます（~/.config/tagpilot/ga4-mcp/device.json、読み取り可能なのはお客様のみです）。デバイス固有の Tag Pilot キーと Google のリフレッシュトークンが保存されます。アクセストークンは約 1 時間ごとに Tag Pilot 経由で更新されます。
• 接続の解除： GA4 MCP ページの接続済みデバイスでデバイスを取り消して更新を停止し、npx -y @tagpilot/ga4-mcp logout を実行してローカルの認証情報を削除し、myaccount.google.com/permissionsでアプリのアクセス権を削除してください。

ツール

すべてのツールは読み取り専用です。プロパティ ID は数値の GA4 ID（例：123456789）であり、G-XXXX の測定 ID ではありません。

ツール	説明
get_account_summaries	読み取り可能な GA4 アカウントとプロパティを、プロパティ ID とともにすべて表示します。まずはこちらを使ってください。
get_property_details	タイムゾーン、通貨、業種、標準版／360、測定 ID を含むデータストリームを表示します。
list_google_ads_links	リンク済みの Google Ads アカウントを表示します。
list_property_annotations	レポートの注釈（リリース、トラッキングの変更、キャンペーン）を表示します。
get_custom_dimensions_and_metrics	API 名（customEvent:…）付きのカスタムディメンション／指標を表示します。必要に応じて標準のものも含められ、検索できます。
run_report	Data API レポートを実行します。ディメンション、指標、日付範囲、フィルター、並べ替え、ページング、合計を指定できます。
run_realtime_report	過去 30 分間（GA4 360 では 60 分間）を表示します。トラッキングの変更が反映されたかを確認するのに便利です。
run_funnel_report	イベントステップからファネルを作成します（パラメーターとディメンションの条件に対応）。オープン／クローズド、内訳、次のアクション、時系列表示に対応します。Google の v1alpha API を使用します。
check_duplicate_transactions	Tag Pilot のチェックです。 transaction_id ごとの購入イベントを確認し、重複率、重複が最も多い ID、ID のない購入を表示します。
check_traffic_attribution	Tag Pilot のチェックです。 チャネルグループごとのセッションと、Unassigned、(not set) の参照元、(not set) のランディングページ、Direct の割合を表示し、考えられる原因も示します。
connect	このコンピューターを接続します。ブラウザーで承認するためのリンクとコードを返します（AI がそれらを表示します。MCP URL エリシテーションに対応するクライアントは、リンクを開くことを提案します）。明示的に開始するには 「GA4 に接続して」 と指示してください。
connection_status	接続済み（デバイス名付き）、承認待ち（リンクとコードを再表示）、未接続、またはエラーの内容を表示します。サインインが開始済みの場合、完了まで最長 25 秒待機します。

レポートの入力

• 日付： YYYY-MM-DD、today、yesterday、または NdaysAgo（例：28daysAgo）。デフォルト：直近の完了した28日間。最大4つの日付範囲を指定できます。複数の日付範囲を指定すると、dateRange 列が追加されます。

• ディメンションと指標： GA4 API 名。例：date、eventName、sessionSourceMedium、 pagePath、sessions、activeUsers、purchaseRevenue (一覧を参照)。

• フィルター： すべて一致する必要がある条件のリストです。{"any": [...]} は条件を OR でグループ化し、 "not": true は条件を否定します。

  [
    {"field": "eventName", "op": "exact", "value": "purchase"},
    {"field": "country", "op": "in_list", "values": ["Poland", "Germany"], "not": true},
    {"any": [
      {"field": "pagePath", "op": "begins_with", "value": "/shop"},
      {"field": "pagePath", "op": "partial_regex", "value": "product"}
    ]}
  ]
  

  演算子：exact、contains、begins_with、ends_with、full_regex、partial_regex、in_list、 eq、lt、lte、gt、gte、between（from／to）、empty。ディメンションフィルターと指標フィルターは、GA4 API と同様に個別の入力です。

• 並べ替え： [{"field": "sessions", "desc": true}]。数値のように見えるディメンションには、dimension_order: "numeric" を使用します。

• 出力： 行は {"date": "20261026", "sessions": 321} のようなオブジェクトです。デフォルトの上限は100行です。続きがある場合は next_offset で確認できます。しきい値処理、サンプリング、(other) 行は notes に記載されます。

トラッキング健全性チェックについて

これらは、いくつかの run_report 呼び出しをもとに作成した、実用的な経験則です。各結果には測定内容が表示されます。たとえば、check_duplicate_transactions は transactionId ごとにグループ化した purchase イベントをカウントし、check_traffic_attribution は未割り当てのトラフィックが5％以上の場合にフラグを立てます。これらの実行に必要な GA4 クォータは、同等のレポートと同じです（レポート呼び出し3～4回分）。

トラブルシューティング

「まだ接続されていません」（リンクと ABCD-1234 のようなコードが表示される）：AI にリンクとコードが表示されます。任意のブラウザーでリンクを開き（このマシン上でなくてもかまいません）、Tag Pilot にサインインして、コードが一致していることを確認し、承認して、Google Analytics へのアクセスを許可します。その後、完了したことを AI に伝えてください。AI は質問を再試行するか、connection_status を呼び出します。サーバーはバックグラウンドで接続を確認し続けるため、再起動は不要です。コードの有効期限は10分です。有効期限が切れた後は、もう一度質問するか、「connect GA4」と伝えて新しいコードを取得してください。代わりにターミナルから接続する場合（SSH 経由など）は、npx -y @tagpilot/ga4-mcp login を実行します。リンクと枠で囲まれたコード、カウントダウンが表示され、承認するまで待機します。

「このコンピューターは Tag Pilot から切断されました」：GA4 MCP ページでデバイスが取り消されたため、保存済みの認証情報が削除されました。もう一度接続するよう依頼してください。

「GA4 の Google サインインの有効期限が切れたか、取り消されました」：保存済みのサインイン情報が削除されました。もう一度依頼して、再度承認してください。Google は、6か月間使用されなかった場合やアクセスを取り消した場合にリフレッシュトークンを失効させます。また、パスワードの変更後にも失効することがあります。

「サインイン中の Google アカウントにはプロパティ … へのアクセス権がありません」：その Google アカウントには、GA4 プロパティの少なくとも閲覧者ロールが必要です。get_account_summaries を使用すると、そのアカウントで読み取り可能な内容を確認できます。別の Google アカウントを使用するには、npx -y @tagpilot/ga4-mcp logout を実行してから、再接続してください。

「Google はこのアプリを確認していません」：Tag Pilot の Google による確認が保留中（ベータ版）の間に表示されます。詳細設定 → Tag Pilot に移動 をクリックしてください。

クォータエラー：GA4 Data API のクォータはプロパティごとに設定され、毎時および毎日補充されます。日付範囲を短くする、ディメンションを減らす、または上限を下げるようにしてください。また、残りのクォータを確認するには return_property_quota: true を指定します。

TAGPILOT_API_KEY を使用している場合：「Tag Pilot が TAGPILOT_API_KEY を拒否しました」／「ga4:mcp スコープがありません」というメッセージは、そのキーが取り消されたか、アプリ内の別の場所で作成されたことを意味します。GA4 MCP ページでキーを作成するか、この変数を削除してデバイス接続を使用してください。サインインすると、「…で Google にサインインを完了してから、もう一度依頼してください」と表示されます。

セットアップを確認する：npx -y @tagpilot/ga4-mcp status を実行すると、このコンピューターが接続されているか（Tag Pilot キーの先頭の文字を表示）と、Google のサインイン状態が表示されます。ログは stderr に出力されます（stdout は MCP チャネルです）。Claude Code では claude --debug または /mcp を確認してください。

設定

必須項目はありません。すべての変数は任意です。

変数
TAGPILOT_API_KEY	GA4 MCP ページで取得する ga4:mcp キー（tpk_…）です。ヘッドレス環境や CI 環境で使用します。デバイス接続を省略し、サインイン情報はキーごとに保存されます。
TAGPILOT_API_URL	Tag Pilot API のベース URL です。デフォルトは https://api.tagpilot.io です。
GA4_MCP_NO_BROWSER	ブラウザーを開かずにリンクを表示／返す場合は 1 を指定します。
GA4_MCP_BROWSER	起動するブラウザーです（macOS ではアプリ名、Linux／Windows ではコマンド）。
GA4_MCP_AUTH_WAIT_SECONDS	ツール呼び出しが接続を待ってからリンクを返すまでの時間です（接続処理はバックグラウンドで続行されます）。デフォルトは 45 秒です（MCP クライアントは 60 秒でタイムアウトすることがよくあります）。
GA4_MCP_CONFIG_DIR	認証情報のディレクトリです。デフォルトは ~/.config/tagpilot/ga4-mcp です。

コマンド：npx -y @tagpilot/ga4-mcp [serve|login|logout|status|--help|--version]。コマンドを指定しない場合は、stdio で MCP サーバーを起動します。logout はこのコンピューターの接続（および保存済みの TAGPILOT_API_KEY のサインイン情報）を削除します。TAGPILOT_API_KEY が設定されている場合は、そのキーのサインイン情報のみを削除します。デバイス自体の認証を取り消すには、GA4 MCP ページを使用してください。

開発

このパッケージは tagpilot/ga4-mcp モノレポにあり、@tagpilot/search-console-mcp と並んでいます。どちらも packages/mcp-core にある Tag Pilot の接続コードと CLI コードを共有しています。リポジトリのルートから実行してください。

npm install
npm run check      # typecheck + lint + unit tests (all packages)
npm run build      # → packages/*/dist/index.js (esbuild bundles the shared core in)
npm run e2e        # built servers over stdio against a mock broker and mock Google
npm run mcpb       # Claude Desktop extensions → packages/*/tagpilot-<name>-<version>.mcpb
npm run mcpb:smoke # unpack each bundle, check its tools, run the e2e against it

バージョンは package.json、src/version.ts、server.json（MCP Registry）、mcpb/manifest.json、およびリポジトリルートの gemini-extension.json に記載されています（Gemini CLI はリポジトリルートから拡張機能をインストールします）。これらの値に不一致があると npm test は失敗します。リリース手順は Tag Pilot リポジトリの explorations/ga4-mcp/distribution.md にあります。

Tag Pilot API とのブローカー契約は、Tag Pilot リポジトリの explorations/ga4-mcp/api-contract.md にあります。

ローカルテストでは、TAGPILOT_API_URL にローカルまたはベータ版の tc-api（http://localhost:8000、https://beta-api.tagpilot.io）を指定してください。GA4_MCP_ADMIN_API_URL と GA4_MCP_DATA_API_URL は、GA4 の呼び出し先をモックに指定するために使用します（npm run e2e で使用）。

ライセンス

Apache License 2.0。Copyright 2026 Tag Concierge sp. z o.o. ライセンスは Tag Pilot の名称やロゴには適用されません（NOTICE を参照）。