gtm-ga4

mcp-gtm-ga4

Google Tag Manager と GA4 向けの MCP サーバーです。Claude を介したタグ管理、同意監査、ワークスペースのバージョン管理、アナリティクスレポートに対応します。

機能

• 14 個のツールで、GTM ワークスペース管理（タグ、トリガー、変数）、同意コンプライアンス監査、ワークスペースのプレビュー／バージョン管理、GA4 レポートに対応します
• サンドボックスの安全性 — すべての書き込み操作で、解決されたワークスペースが対象であることを確認し、サンドボックス以外のワークスペースへの書き込みを拒否します
• 複数クライアントのサポート — 環境変数でクライアントごとに設定できます
• デフォルトのワークスペース ID を自動検出 — カスタムサンドボックスを使用する場合を除き、ワークスペース ID を手動で指定する必要はありません

インストール

npm install mcp-gtm-ga4

または、クローンしてビルドします。

git clone https://github.com/mharnett/mcp-gtm-ga4.git
cd mcp-gtm-ga4
npm install
npm run build

設定

セキュリティ： .mcp.json ファイルを共有したり、Git にコミットしたりしないでください。API 認証情報が含まれている場合があります。.mcp.json を .gitignore に追加してください。

ランタイム設定は環境変数で行います。

変数	必須	説明
GOOGLE_APPLICATION_CREDENTIALS	はい	Google 認証情報 JSON キーファイルのパス（サービスアカウント または 認証済みユーザー。詳しくは「認証」を参照）
GTM_ACCOUNT_ID	はい	GTM アカウント ID
GTM_CONTAINER_ID	はい	GTM コンテナ ID
GA4_PROPERTY_ID	はい	GA4 プロパティ ID
GTM_SANDBOX_WORKSPACE_ID	いいえ	ワークスペース ID の上書き（省略した場合はデフォルトのワークスペースを自動検出）
MCP_SERVER_NAME	いいえ	サーバー名（デフォルトはパッケージ名 mcp-gtm-ga4）

参照用のテンプレートについては config.example.json をご覧ください。ディスクから読み込まれる値は oauth.scope（任意の config.json 内）のみです。これは、オンボーディングの各手順で要求する OAuth スコープの唯一の信頼できる情報源です。config.json がない場合は、コミット済みの最小スコープが使用されます。

認証

この MCP は 2 種類の認証方式に対応しています。どちらも同じ GOOGLE_APPLICATION_CREDENTIALS ランタイムパスを使用します。

優先順位と仕組み

ランタイムにサービスアカウントと OAuth を切り替える設定はありません。どちらの方式も単一の設定先である GOOGLE_APPLICATION_CREDENTIALS に集約され、ランタイムはその値を GoogleAuth({ keyFile }) に渡します。この環境変数に指定したファイルが認証情報となります。

• サービスアカウントの JSON キー（以下のオプション 1）、または
• auth サブコマンドが書き込む authorized_user キーファイル（オプション 2）。こちらもまったく同じ設定先で使用されるファイルです。

つまり、実際に適用される優先ルールはエラー処理のみです。**明示的に設定されたキーファイルが使用され、GOOGLE_APPLICATION_CREDENTIALS が未設定の場合、サーバーは起動時にエラーで停止します。**このオンボーディングエラーには、サービスアカウントのパスと auth OAuth ヘルパーの両方が記載されます。Google の Application Default Credentials（gcloud ユーザー認証情報／GCE メタデータサーバー）にはフォールバックしません。マシンローカルのデフォルト認証情報を暗黙に使うことも、ランタイム中に暗黙に別の認証方式へ切り替えることもありません。

1. サービスアカウント（主な方法。無人実行／サーバー用途に推奨）

GCP プロジェクトにサービスアカウントを作成し、その JSON キーをダウンロードして、GTM コンテナのロール（対象の GTM コンテナ上）と GA4 プロパティへのアクセス権を付与し、GOOGLE_APPLICATION_CREDENTIALS にキーファイルのパスを指定します。OAuth フロー、ブラウザー、リフレッシュトークンは不要です。ヘッドレス環境、サーバー、無人実行のデプロイには、この方法を推奨します。

2. ユーザー OAuth（対話型。サービスアカウントを使用できないユーザー向け）

サービスアカウントを使用できない場合は、ご自身の Google OAuth クライアント（ご自身の GCP プロジェクトで作成した「デスクトップアプリ」の OAuth 2.0 クライアント ID。Tag Manager API と Google Analytics Admin API および Data API を有効にしてください）を使って、ユーザー認証情報を取得します。オンボーディングコマンドは同等のものが 2 種類あり、どちらも PKCE（RFC 7636、S256）で保護され、config.json の oauth.scope に指定されたスコープを要求するため、設定にずれが生じません。

export GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
export GOOGLE_CLIENT_SECRET=your-client-secret

# Option A: write an authorized_user credential file directly
node dist/index.js auth --output ./gtm-ga4-credentials.json
# then set GOOGLE_APPLICATION_CREDENTIALS=./gtm-ga4-credentials.json

# Option B: the standalone helper (prints GOOGLE_REFRESH_TOKEN + a ready-to-save
# authorized_user JSON you can write to a file for GOOGLE_APPLICATION_CREDENTIALS)
node get-refresh-token.cjs

リフレッシュトークン／認証情報はご自身で書き込み、環境からのみ読み取られます。情報が共有されることはなく、OAuth クライアントのキーファイルも同梱されていません。共有ログに標準出力をリダイレクトしてヘルパーを実行しないでください。設計上、リフレッシュトークンが標準出力に表示されます。

要求する OAuth スコープ

オンボーディングの各手順では、この MCP のツールが使用するスコープのみを要求します（config.example.json → oauth.scope）。

スコープ	必要とするツール
tagmanager.edit.containers	gtm_create_tag、gtm_update_tag、gtm_create_variable、gtm_update_variable、gtm_delete_variable、タグ／トリガー／変数の読み取り
tagmanager.edit.containerversions	gtm_create_version
tagmanager.publish	gtm_create_version、gtm_preview（クイックプレビュー）
analytics.readonly	gtm_ga4_run_report、gtm_ga4_realtime_report、gtm_ga4_list_custom_dimensions
analytics.edit	gtm_ga4_create_custom_dimension

tagmanager.readonly は意図的に要求しません。編集スコープですでに読み取りアクセスが許可されているためです。

使用方法

Claude Code（.mcp.json）

{
  "mcpServers": {
    "gtm-ga4": {
      "command": "node",
      "args": ["/path/to/mcp-gtm-ga4/dist/index.js"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account.json",
        "GTM_ACCOUNT_ID": "1234567890",
        "GTM_CONTAINER_ID": "9876543",
        "GA4_PROPERTY_ID": "331956119"
      }
    }
  }
}

npx

GTM_ACCOUNT_ID=1234567890 \
GTM_CONTAINER_ID=9876543 \
GA4_PROPERTY_ID=331956119 \
GOOGLE_APPLICATION_CREDENTIALS=/path/to/sa.json \
npx mcp-gtm-ga4

Claude Desktop： macOS の場合は ~/Library/Application Support/Claude/claude_desktop_config.json に、Windows の場合は %APPDATA%\Claude\claude_desktop_config.json に追加します。

安全性

ワークスペースのサンドボックス保護

すべての書き込み操作（gtm_update_tag、gtm_create_tag、gtm_preview、gtm_create_version）では、実行前に対象が解決済みのワークスペースであることを確認します。異なるワークスペースへの書き込みを試みるリクエストに対して、サーバーは SafetyError を返し、操作をブロックします。

これにより、MCP サーバーがサンドボックスワークスペースに対して設定されている場合に、本番環境を誤って変更することを防ぎます。

ツール

GTM タグ

ツール	説明
gtm_list_tags	同意ステータスと発火トリガーを含む、ワークスペース内のすべてのタグを一覧表示します
gtm_get_tag	タグ ID でタグの完全な設定を取得します
gtm_update_tag	既存のタグを更新します（JSON によるマージパッチ）
gtm_create_tag	JSON 定義から新しいタグを作成します

GTM 構造

ツール	説明
gtm_list_triggers	すべてのトリガー（ID、名前、タイプ）を一覧表示します
gtm_list_variables	すべての変数（ID、名前、タイプ）を一覧表示します

GTM 同意

ツール	説明
gtm_audit_consent	同意設定への準拠状況について、すべてのタグを監査します

GTM ワークスペース

ツール	説明
gtm_preview	現在のワークスペースのクイックプレビューを生成します
gtm_create_version	ワークスペースから新しいコンテナバージョンを作成します

GA4 レポート

ツール	説明
gtm_ga4_run_report	ディメンション、指標、日付範囲、フィルターを指定して GA4 レポートを実行します
gtm_ga4_realtime_report	GA4 リアルタイムレポート（過去 30 分間）を実行します

GA4 管理

ツール	説明
gtm_ga4_list_custom_dimensions	プロパティのすべてのカスタムディメンションを一覧表示します
gtm_ga4_create_custom_dimension	新しいカスタムディメンションを作成します

アーキテクチャ

• GTM API：googleapis（Tag Manager v2）
• GA4 データ：@google-analytics/data（BetaAnalyticsDataClient）
• GA4 管理：@google-analytics/admin（AnalyticsAdminServiceClient）
• レジリエンス：cockatiel（リトライ、サーキットブレーカー、タイムアウトポリシー）
• ロギング：pino と pino-pretty
• トランスポート：MCP SDK の stdio トランスポート

ライセンス

MIT

作者

Mark Harnett / drak-marketing が作成