samarth-gtm-mcp

Samarth Analytics MCP

Claude Desktop、Claude Code、Cursor などの AI アシスタントが Google Tag Manager と GA4 を操作できる、オープンソースの Model Context Protocol (MCP) サーバーです。サーバーサイドコンテナを含む GTM API v2 の全機能（100 以上のツール）、GA4 Admin API と Data API、組み込みの実装監査、さらにウェブサイトをクロールしてタグと Consent Mode v2 の設定を確認する第 2 のサーバーを備えています。Samarth Analytics が自社のクライアント業務向けに開発し、アナリティクスコミュニティ向けに MIT ライセンスで公開しています。

デフォルトでは読み取り専用です。 作成、更新、公開、削除はそれぞれ個別の環境フラグで制御され、すべての書き込みには confirm=true も必要です。また、API に変更を加えずに書き込みをシミュレートするドライランモードもあります。ガードレールを参照してください。

ご自身の責任で使用し、まずはダミーコンテナで試してください。 このサーバーはお使いの Google 認証情報で動作するため、行われた変更はすべてご自身のものです。最初はサンドボックスの GTM コンテナとテスト用の GA4 プロパティで試し、動作を確認するまでは書き込みフラグをオフにしておき、書き込みを行ったセッションの後はコンテナのバージョン履歴を確認してください。私たちは本番環境で使用していますが、お客様の環境は私たちのものとは異なります。

3 つの利用方法

	利用できるもの	開始方法
ホスト型、インストール不要	https://mcp.samarthanalytics.com/mcp にあるコミュニティ向けインスタンスです。ご自身の Google アカウントでサインインすると、自分のコンテナとプロパティのみが表示され、読み取り専用に制限されています。共有型で、ベストエフォートで提供され、稼働時間の保証はありません。	mcp-remote を使って MCP クライアントに追加します。 {"mcpServers":{"samarth-gtm":{"command":"npx","args":["mcp-remote@next","https://mcp.samarthanalytics.com/mcp"]}}}
ローカル	ご自身の Google OAuth クライアントを使って、お使いのマシンで stdio 経由で動作するサーバーです。書き込みフラグはご自身で管理できます。	クイックスタートとGoogle Cloud OAuth の設定
セルフホスト	MCP サーバー、ウェブ監査サーバー、キャプチャワーカーをひとつの docker-compose スタックとして、ご自身のトークンの背後に配置します。	docs/SELF_HOSTING_DOCKER.mdとクラウドデプロイ

このリポジトリには、チャット UI を備え、このサーバーを組み込んだローカルの Electron アプリ Samarth Desktop（クイックスタート）と、ライブで読み取り専用の QC 監査を実行するブラウザーベースの顧客ポータル apps/portal/ も含まれています。

コントリビューションを歓迎します。 再現可能なコンテナ設定を添えたバグ報告が、最も役立ちます。まずCONTRIBUTING.mdをお読みください。CI はすべてのプルリクエストで実行されます。

---

目次

1. 機能
2. クイックスタート
3. Google Cloud OAuth の設定
4. サービスアカウントの制限事項
5. 環境変数リファレンス
6. ガードレール
7. 利用可能なツール
8. クラウドデプロイ
9. セキュリティに関する注意事項
10. 開発
11. リリース
12. トラブルシューティング

---

機能

• GTM API v2 の全機能に対応 — アカウント、コンテナ、ワークスペース、タグ、トリガー、変数、フォルダー、組み込み変数、バージョン、同期、公開、プレビュー
• サーバーサイドおよび高度な GTM 機能に対応 — 環境、ユーザー権限、送信先、クライアント、変換、ゾーン、カスタムテンプレート、gtag 設定に加え、コンテナスニペット／検索／統合／タグ ID の移動、ワークスペースの変更差分ステータス
• GA4 に対応 — GA4 Admin ツール（ga4_*）に加え、意図と実際の差異を照合する GA4 Data API レポート（ga4_run_report、ga4_run_realtime_report）を利用できます。読み取りとレポートには analytics.readonly のみが必要です。GA4 Admin の書き込みツールはデフォルトで無効になっており、GA4_MCP_ENABLE_WRITES／GA4_MCP_ENABLE_DELETES で有効化できます。また、analytics.edit も必要です
• 自動ページネーション — ページネーションに対応したすべてのリストツールは、nextPageToken を自動的にたどってすべての結果を返します。maxPages／pageToken で上限を指定することもできます
• 指数バックオフとジッターによる再試行 — 読み取りリクエストで一時的な Google API エラー（HTTP 408／429／5xx、ネットワークエラー）が発生した場合、自動的に再試行します。変更操作は自動再試行されません（GTM_MCP_RETRY_* で調整可能）
• 2 つのトランスポートモード：stdio（ローカル、Claude Desktop／Cursor 向け）と Streamable HTTP（クラウド／チーム向け）
• デフォルトのガードレール：明示的に有効化しない限り読み取り専用。公開と削除は個別に制限
• ドライランモード：API に変更を加えず、すべての書き込みをシミュレート
• すべての書き込み／削除／公開操作で confirm=true が必須
• 監査ツール：ワークスペースを調べ、よくある GA4／GTM の実装上の問題を検出
• エクスポートツール：ワークスペース全体を構造化 JSON として出力
• すべての入力を Zod スキーマで検証
• 詳細な Google API エラーメッセージを MCP クライアントに表示

---

クイックスタート

Samarth の実行には、デスクトップアプリを使用します。チャット UI を備え、MCP サーバーをプロセス内に組み込んだローカルの Electron アプリです。複数の Google アカウントでサインインでき、アカウントごとに LLM キー（OpenAI／Anthropic／Gemini）を設定でき、シークレットは OS のキーチェーンに保存されます。手動で設定する必要はありません。初回起動時に、Google OAuth クライアントと LLM キーをアプリに入力します。

必要なもの： Node.js 18 以降、Git、 および無料の Google「デスクトップアプリ」OAuth クライアント。Google Cloud プロジェクトで一度だけ作成する 2 つの値が必要です（手順をクリックごとに詳しく説明）。

git clone https://github.com/samarthanalytics-sj/samarth-analytics-mcp.git
cd samarth-analytics-mcp/apps/desktop
npm install    # downloads the Electron binary (~100 MB first time)
npm run dev

ウィンドウが開いたら、OAuth クライアント ID とシークレット、LLM API キーを入力するよう求められたときに貼り付け、Google にサインインして、GTM／GA4 の設定についてチャットを始めます。

アプリに入力する代わりに設定ファイルを使いますか？ OAuth クライアントを .env ファイルに記述すると、アプリの起動時に読み込まれます（アプリに入力した値と実際のシェル変数は、常にこちらより優先されます）。

GOOGLE_DESKTOP_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_DESKTOP_CLIENT_SECRET=your-client-secret

apps/desktop/.env またはリポジトリのルートに保存してください（すでに gitignore の対象です。コミットしないでください）。サーバーの GOOGLE_OAUTH_CLIENT_ID／GOOGLE_OAUTH_CLIENT_SECRET という名前を使ったリポジトリルートの .env も使用できるため、アプリと MCP サーバーの両方で 1 つのファイルを共有できます。パッケージ版のインストールでは、代わりにデータディレクトリ（Windows では %APPDATA%）から .env を読み込みます。

その後の普段の起動方法は、次のとおりです。

cd samarth-analytics-mcp/apps/desktop && npm run dev

Windows／macOS 固有の情報、初回セットアップ、実際の .exe／.dmg インストーラーのビルド、Error: Electron uninstall の修正方法を含む完全なガイド： apps/desktop/INSTALL.md。

---

Google Cloud OAuth の設定

ステップ 1：GTM API を有効にする

1. Google Cloud Console にアクセスします
2. プロジェクトを選択するか、新規作成します
3. APIs & Services → Library に移動します
4. **「Tag Manager API」**を検索し、Enable をクリックします
5. **「Google Analytics Admin API」**を検索し、Enable をクリックします（読み取り専用の ga4_* Admin ツールに必要です）
6. **「Google Analytics Data API」**を検索し、Enable をクリックします（ga4_run_report／ga4_run_realtime_report に必要です）

ステップ 2：OAuth 2.0 認証情報を作成する

1. API とサービス → 認証情報 に移動します
2. 認証情報を作成 → OAuth 2.0 クライアント ID をクリックします
3. アプリケーションの種類を選択します：
   • デスクトップアプリ — ローカルの stdio で使用する場合に最も簡単です（リダイレクト URI は不要です）
   • ウェブアプリケーション — HTTP サーバー用です（リダイレクト URI を追加します）
4. JSON をダウンロードするか、クライアント ID と クライアント シークレット をコピーします
5. .env に追加します：

   GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
   GOOGLE_CLIENT_SECRET=your-client-secret
   GOOGLE_REDIRECT_URI=http://localhost:3001/oauth/callback
   

ステップ 3：OAuth 同意画面を設定する

1. API とサービス → OAuth 同意画面 に移動します
2. 外部 を選択します（Google Workspace をご利用の場合は「内部」）
3. アプリ名とサポートメールアドレスを入力します
4. スコープを追加します：
   • https://www.googleapis.com/auth/tagmanager.readonly
   • https://www.googleapis.com/auth/tagmanager.edit.containers
   • https://www.googleapis.com/auth/tagmanager.edit.containerversions
   • https://www.googleapis.com/auth/tagmanager.manage.accounts
   • https://www.googleapis.com/auth/tagmanager.manage.users
   • https://www.googleapis.com/auth/tagmanager.publish
   • https://www.googleapis.com/auth/analytics.readonly（読み取り専用の GA4 Admin および Data API ツール）
   • https://www.googleapis.com/auth/analytics.edit（GA4 Admin の書き込みツール — GA4_MCP_ENABLE_WRITES によって制御されます）
   • https://www.googleapis.com/auth/analytics.manage.users（GA4 のアクセス権バインディング用書き込みツール）
5. アプリが「テスト」モードの間に、ご自身の Google アカウントをテストユーザーとして追加します

注：個人または代理店での使用であれば、アプリを「テスト」モードのままにして問題ありません。アプリを公開するか、確認を受けない限り、7 日ごとに再認証が必要です。

ステップ 4：OAuth のセットアップを実行する

npm run auth:google

または、以前のコード貼り付けヘルパーを使用する場合：

npm run oauth:setup

---

サービスアカウントの制限事項

概要：サービスアカウントは、デフォルトでは GTM で動作しません。OAuth 2.0 を使用してください。

Google Tag Manager API はユーザーデータ APIです。個々の Google アカウントが所有するリソースを管理します。サービスアカウントは Google ユーザーではないため、GTM コンテナへのアクセス権は自動的に付与されません。

オプション A：サービスアカウントを GTM ユーザーとして追加する（最も簡単）

それでもサービスアカウントを使用する場合：

1. サービスアカウントのメールアドレスを取得します（例：[email protected]）
2. GTM で、アカウントまたはコンテナの 管理 → ユーザー管理 に移動します
3. 適切なロール（閲覧、編集、承認、公開）を付与して、サービスアカウントのメールアドレスを追加します
4. .env に GOOGLE_SERVICE_ACCOUNT_KEY_FILE=/path/to/key.json を設定します

注意事項：これは、GTM コンテナが Google Workspace の外部共有制限付きアカウントではなく、Google アカウントに関連付けられている場合にのみ動作します。

オプション B：ドメイン全体の委任（Google Workspace のみ）

Google Workspace 組織の場合：

1. JSON キーを使用してサービスアカウントを作成します
2. Google Cloud Console で、サービスアカウントのドメイン全体の委任を有効にします
3. Google Workspace 管理コンソール → セキュリティ → API の制御 → ドメイン全体の委任で：
   • サービスアカウントのクライアント ID を追加します
   • スコープを追加します：https://www.googleapis.com/auth/tagmanager.edit.containers（必要に応じてその他のスコープも追加します）
4. .env に次のように設定します：

   GOOGLE_SERVICE_ACCOUNT_KEY_FILE=/path/to/key.json
   

5. buildGoogleAuth() でサブジェクトを設定すると、サーバーはユーザーを自動的に偽装します

注意事項：有料の Google Workspace アカウントが必要です。ご自身のドメインでのみ利用できます。

---

環境変数リファレンス

変数	デフォルト	説明
GOOGLE_OAUTH_CLIENT_ID	—	OAuth クライアント ID（優先）。GOOGLE_CLIENT_ID にフォールバックします。
GOOGLE_OAUTH_CLIENT_SECRET	—	OAuth クライアントシークレット（優先）。GOOGLE_CLIENT_SECRET にフォールバックします。
GOOGLE_OAUTH_REDIRECT_URI	http://localhost:3001/oauth/callback	OAuth リダイレクト URI。GOOGLE_REDIRECT_URI にフォールバックします。
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET / GOOGLE_REDIRECT_URI	—	従来の名前で、引き続きサポートされています。
SAMARTH_GOOGLE_OAUTH_CLIENT_ID	—	ホステッド環境のみ。 Samarth が所有する公開 OAuth クライアントです。設定されている場合、セルフホスト用の変数より優先されます。
SAMARTH_GOOGLE_OAUTH_CLIENT_SECRET	—	ホステッド環境のみ。 プラットフォームのシークレットマネージャーから注入してください。コミットしないでください。
GOOGLE_ACCESS_TOKEN	—	現在の OAuth アクセストークンです。環境変数はトークンファイルより優先されます。
GOOGLE_REFRESH_TOKEN	—	OAuth リフレッシュトークン（長期間有効）です。環境変数はトークンファイルより優先されます。
GTM_MCP_TOKEN_FILE	./.gtm-mcp-tokens.json	npm run auth:google が書き込むローカル OAuth トークンファイルへのパス（gitignore 対象）。
GOOGLE_SERVICE_ACCOUNT_KEY_FILE	—	サービスアカウント JSON キーへのパス（上記の制限事項を参照）
GTM_MCP_TRANSPORT	stdio	トランスポート：stdio または http
GTM_MCP_HTTP_PORT	3001	HTTP サーバーのポート（http トランスポートのみ。PORT にフォールバックします）
GTM_MCP_HTTP_AUTH_TOKEN	—	/mcp を保護するベアラートークン（http トランスポート）。これも STYTCH_PROJECT_ID も設定されていない場合、HTTP トランスポートは起動を拒否します。
GTM_MCP_HTTP_ALLOW_UNAUTHENTICATED	false	ローカル開発時に、認証なしでの起動を許可します。GTM_MCP_HTTP_HOST で上書きしない限り、ループバックのみにバインドします。
GTM_MCP_HTTP_HOST	—	バインドするホスト。認証なしの場合はループバック、認証ありの場合はすべてのインターフェースがデフォルトです。
STYTCH_PROJECT_ID	—	これを設定すると、HTTP トランスポートがマルチユーザーモードに切り替わります。各 /mcp リクエストには、そのユーザー自身の Google ID に解決される Stytch JWT が含まれます。未設定の場合は単一 ID モードです。Connected App のアクセストークンのみ受け付けます（client_id が必須で、セッション JWT は拒否されます）。また、発行者と対象者は常に固定されます。STYTCH_JWT_ISSUER / STYTCH_JWT_AUDIENCE のデフォルト値はそれぞれ stytch.com/<project id> / <project id> です（.env.example を参照）。
STYTCH_SECRET	—	Stytch プロジェクトシークレット（サーバー専用）です。STYTCH_PROJECT_ID が設定されている場合は必須で、未設定だとサーバーは終了します。
STYTCH_PUBLIC_TOKEN	—	/oauth/authorize ページで使用する公開可能なトークンです。シークレットではありません。
GTM_MCP_PUBLIC_URL	http://localhost:<port>	このサーバーの公開オリジンです。OAuth Protected Resource Metadata ドキュメントで通知されます。
GTM_MCP_ENABLE_WRITES	false	作成／更新操作を許可します
GTM_MCP_ENABLE_PUBLISH	false	公開操作を許可します
GTM_MCP_ENABLE_DELETES	false	削除操作を許可します
DRY_RUN	false	API を呼び出さずにすべての書き込みをシミュレートします
GTM_MCP_RETRY_MAX	3	一時的な読み取り失敗（408/429/5xx、ネットワーク）の再試行回数です。0 にすると再試行を無効にします。変更操作は自動再試行されません。
GTM_MCP_RETRY_MAX_DELAY_MS	30000	1 回のバックオフ待機時間の上限（ジッター付き指数バックオフ）
GTM_MCP_RETRY_TOTAL_TIMEOUT_MS	60000	最初のリクエストから最後の再試行までの合計実時間の上限

---

ガードレール

サーバーは、confirm=true の要件に加えて、互いに独立した3つのガードレールを適用します。

ガードレール	環境変数	制御対象
書き込みガード	GTM_MCP_ENABLE_WRITES=true	すべての create および update 操作
削除ガード	GTM_MCP_ENABLE_DELETES=true	すべての delete 操作
公開ガード	GTM_MCP_ENABLE_PUBLISH=true	すべてのバージョン公開操作
ドライラン	DRY_RUN=true	API 呼び出しを行わずにシミュレーションします（すべてを上書きします）

環境変数の設定にかかわらず、書き込み／削除／公開ツールでは常に confirm=true が必要です。これにより、ガードレールが有効な場合でも、誤った変更を防止できます。

推奨設定

読み取り専用での探索（デフォルト — チームで共有する場合も安全です）：

GTM_MCP_ENABLE_WRITES=false
GTM_MCP_ENABLE_PUBLISH=false
GTM_MCP_ENABLE_DELETES=false

開発ワークスペースの編集（公開なし）：

GTM_MCP_ENABLE_WRITES=true
GTM_MCP_ENABLE_PUBLISH=false
GTM_MCP_ENABLE_DELETES=false

フルアクセス（注意して使用してください）：

GTM_MCP_ENABLE_WRITES=true
GTM_MCP_ENABLE_PUBLISH=true
GTM_MCP_ENABLE_DELETES=true

---

利用可能なツール

アカウント

ツール	説明
accounts_list	アクセス可能なすべての GTM アカウントを一覧表示します
accounts_get	特定のアカウントを取得します

コンテナ

ツール	説明
containers_list	アカウント内のコンテナを一覧表示します（自動ページネーション）
containers_get	特定のコンテナを取得します
containers_create	✏️ 新しいコンテナを作成します
containers_snippet	コンテナの GTM インストールスニペットを取得します
containers_lookup	リンクされたデスティネーション／タグ ID（例：G-XXXX）でコンテナを検索します
containers_combine	✏️ 別のコンテナをこのコンテナに統合（マージ）します
containers_move_tag_id	✏️ タグ ID を新しいコンテナに移動します

デスティネーション

ツール	説明
destinations_list	コンテナにリンクされたデスティネーション（Google タグ／GA4）を一覧表示します
destinations_get	特定のデスティネーションを取得します
destinations_link	✏️ デスティネーションをコンテナにリンクします

ワークスペース

ツール	説明
workspaces_list	コンテナ内のワークスペースを一覧表示します（自動ページネーション）
workspaces_get	特定のワークスペースを取得します
workspaces_create	✏️ 新しいワークスペースを作成します
workspace_get_status	バージョン作成前に変更差分（変更されたエンティティとマージ競合）を確認します
workspace_sync	✏️ ワークスペースを最新のコンテナバージョンと同期します
workspace_resolve_conflict	✏️ マージ競合を解決します
workspace_quick_preview	プレビューリンクを生成します（読み取り専用で安全）
workspace_create_version_and_publish	🚀 1回の操作でバージョンを作成して公開します

タグ

ツール	説明
tags_list	ワークスペース内のすべてのタグを一覧表示します
tags_get	特定のタグを取得します
tags_create	✏️ タグを作成します
tags_update	✏️ タグを更新します
tags_delete	🗑️ タグを削除します

トリガー

ツール	説明
triggers_list	すべてのトリガーを一覧表示します
triggers_get	特定のトリガーを取得します
triggers_create	✏️ トリガーを作成します
triggers_update	✏️ トリガーを更新します
triggers_delete	🗑️ トリガーを削除します

変数

ツール	説明
variables_list	ユーザー定義変数をすべて一覧表示します
variables_get	特定の変数を取得します
variables_create	✏️ 変数を作成します
variables_update	✏️ 変数を更新します
variables_delete	🗑️ 変数を削除します

フォルダー

ツール	説明
folders_list	すべてのフォルダーを一覧表示します
folders_get	特定のフォルダーを取得します
folders_entities	フォルダー内のエンティティを一覧表示します（自動ページネーション）
folders_create	✏️ フォルダーを作成します
folders_update	✏️ フォルダーを更新します
folders_delete	🗑️ フォルダーを削除します
folders_move_entities	✏️ エンティティをフォルダーに移動します

組み込み変数

ツール	説明
built_in_variables_list	有効な組み込み変数を一覧表示します
built_in_variables_enable	✏️ 組み込み変数を有効にします
built_in_variables_disable	🗑️ 組み込み変数を無効にします
built_in_variables_revert	✏️ 組み込み変数をベースバージョンに戻します

バージョン

ツール	説明
versions_list	バージョンのヘッダー一覧を取得
versions_get	バージョンを取得（現在のライブバージョンは「live」を渡します）
versions_create	✏️ ワークスペースからチェックポイントバージョンを作成
versions_set_latest	✏️ バージョンを最新として設定
versions_publish	🚀 特定のバージョンを公開
versions_undelete	✏️ バージョンを復元
versions_delete	🗑️ バージョンを削除

環境

ツール	説明
environments_list	コンテナ内の環境一覧を取得（自動ページネーション）
environments_get	特定の環境を取得
environments_create	✏️ 環境を作成
environments_update	✏️ 環境を更新
environments_reauthorize	🚀 環境の認証トークンを再生成（影響大）
environments_delete	🗑️ 環境を削除

ユーザー権限（アカウントレベル）

ツール	説明
user_permissions_list	アカウントのユーザー権限一覧を取得（自動ページネーション）
user_permissions_get	特定のユーザー権限を取得
user_permissions_create	✏️ ユーザーにアカウント／コンテナへのアクセス権を付与
user_permissions_update	✏️ ユーザーのアクセスレベルを更新
user_permissions_delete	🗑️ ユーザーのアクセス権を取り消し

サーバーサイドおよび高度なコンテナリソース

これらは GTM API v2 のワークスペーススコープのリソースです。本文が深くネストされているため、作成／更新ではリソース全体を JSON 文字列（bodyJson）として渡します。各リソースは *_list（自動ページネーション）、*_get、*_create ✏️、*_update ✏️、*_delete 🗑️ に対応し、gtag_config を除き *_revert ✏️ にも対応します。

リソース	ツール	備考
クライアント	clients_*	サーバーコンテナのリクエストクライアント
変換	transformations_*	サーバーコンテナのイベント変換
ゾーン	zones_*	ゾーンの委任
テンプレート	templates_*	カスタム／ギャラリーからインストールしたテンプレート
Gtag Config	gtag_config_*	Google タグ（gtag）の設定 — revert なし

アナリティクスとエクスポート

ツール	説明
audit_container	ワークスペースを調査してアナリティクスの問題を確認
export_container	ワークスペースを構造化 JSON としてエクスポート

GA4 管理（読み取り専用）

Google Analytics Admin API（v1beta。拡張計測用の v1alpha 呼び出しを1つ含みます）を使用する読み取り専用ラッパーです。GA4 リソースへの書き込み、更新、削除は行わず、confirm フラグも必要ありません。シニア監査フレームワークの GA4_ADMIN チェック（カスタムディメンション／指標、データストリームと測定 ID、データ保持、拡張計測、キーイベント、Google Ads リンク）を支えます。

https://www.googleapis.com/auth/analytics.readonly スコープと、Google Cloud プロジェクトで有効にしたGoogle Analytics Admin APIが必要です。スコープに関する 403 エラーが表示された場合は、npm run auth:google を再実行してください。

ツール	説明
ga4_account_summaries_list	GA4 アカウントとそのプロパティの概要を一覧表示します（検出の出発点として最適です）
ga4_properties_list	親アカウント配下のプロパティを一覧表示します（表示名、タイムゾーン、通貨、サービスレベル）
ga4_property_get	ID を指定して単一のプロパティを取得します
ga4_data_streams_list	データストリーム（ウェブ／Android／iOS）を一覧表示します。ウェブの測定 IDも含まれます
ga4_enhanced_measurement_get	ウェブデータストリームの拡張計測設定を取得します（v1alpha）
ga4_custom_dimensions_list	カスタムディメンションを一覧表示します（パラメーター、スコープ）
ga4_custom_metrics_list	カスタム指標を一覧表示します（パラメーター、単位、スコープ）
ga4_data_retention_get	イベントデータの保持設定を取得します
ga4_key_events_list	キーイベントを一覧表示します（以前の「コンバージョンイベント」。現在の Admin での名称です）
ga4_google_ads_links_list	Google Ads リンクを一覧表示します（顧客 ID、自動タグ設定／広告パーソナライズのフラグ）

プロパティ／アカウントが必要な箇所では、数値のみの ID（123456789）と完全修飾形式（properties/123456789、accounts/123456）のどちらも使用できます。

文書化されている制限事項（GA4 Admin API v1beta では公開されていないため、偽装して実装するのではなく、意図的に実装していません）：

• 内部トラフィック／不要な参照元のデータフィルタ — 公開された dataFilters コレクションがありません。データストリームごとに設定します。
• 参照元の除外 — 専用の Admin API リソースがありません。
• チャネルグループとオーディエンス — v1alpha のみで利用できるため、この読み取り専用 v1beta セットの対象外です。

GA4 Data API（読み取り専用レポート）

Google Analytics Data API（v1beta）を使用する読み取り専用ラッパーです。書き込みは行わず、confirm フラグも必要ありません。意図と実際の状況の照合に使用します。つまり、コンテナから送信するように設定されたイベントと、GA4 が実際にレポートするイベントを比較します（設定済みのイベントで報告されたアクティビティがゼロの場合は、問題を示す兆候です）。

GA4 Admin ツールと同じ https://www.googleapis.com/auth/analytics.readonly スコープを使用するため、追加の同意は必要ありません。Google Cloud プロジェクトでGoogle Analytics Data APIを有効にしてください。

ツール	説明
ga4_run_report	日付範囲を指定してレポートを実行します（ディメンションと指標。例：eventName ごとの eventCount）。limit、offset、並べ替えに対応しています
ga4_run_realtime_report	リアルタイムレポートを実行します（およそ直近30分間のイベント）。ライブ QA に使用します

文書化されている未対応機能（偽装して公開するのではなく、意図的に公開していません）：ピボットレポート、コホート、ファネル。

ページネーション

ページネーション対応の GTM エンドポイントを利用するすべてのリストツール（accounts_* スコープのコンテナ、 ワークスペース、タグ、トリガー、変数、フォルダー、フォルダー内のエンティティ、環境、 ユーザー権限、クライアント、変換、ゾーン、テンプレート、gtag 設定）は、 デフォルトでページネーションを自動的にたどり、すべての結果を返します。省略可能な引数：

• maxPages — 取得する API ページ数の上限です（デフォルトは 50）。残りのページがある場合、 レスポンスに "truncated": true と nextPageToken が含まれます。
• pageToken — 前回の切り詰められた結果から再開します。

切り詰められていないレスポンスでは、元の { <key>: [...], count } 形式が変更されずに維持されます。

リストキーだけでは返される内容を表せないため、2 つのツールは動作が異なります：

• folders_entities は、並行する3つのコレクション（tag、trigger、variable。常に存在し、フォルダーに該当するものがない場合は空）と counts オブジェクトを返します。ページ上限に達した場合にのみ、truncated／nextPageToken が追加されます。
• export_container は5つのコレクションを個別にページ分割するため、maxPages（コレクションごとに適用）は指定できますが、pageToken は指定できません。短いエクスポートには、デフォルトの summary を含むすべての形式で、incomplete: true、truncatedCollections、コレクションごとの nextPageTokens、および warning が付けられます。

凡例：✏️ は GTM_MCP_ENABLE_WRITES=true が必要 | 🗑️ は GTM_MCP_ENABLE_DELETES=true が必要 | 🚀 は GTM_MCP_ENABLE_PUBLISH=true が必要

✏️ 🗑️ 🚀 のすべてのツールでは、ツール引数に confirm: true も必要です。

---

クラウドデプロイ

トランスポート

クラウドにデプロイする場合は、GTM_MCP_TRANSPORT=http を使用します。サーバーが公開するエンドポイント：

• POST /mcp — Streamable HTTP MCP エンドポイント
• GET /mcp — 既存セッション用の SSE ストリーム
• DELETE /mcp — セッションの終了
• GET /health — ヘルスチェック

このサーバーには /oauth/callback ルートはありません。npm run auth:google はリダイレクト用に、127.0.0.1:3001 で独自の短時間リスナーを実行します。ホストされたトランスポートで認証されていないコールバックを受け付けると、サーバーに保存された Google 認証情報が上書きされるおそれがあるため、このルートは削除されました。

リモートクライアントの接続

Streamable HTTP に対応しているクライアントは、/mcp エンドポイントに直接接続できます。Claude Desktop のように stdio のみに対応しているクライアントでは、mcp-remote をプロキシとして使用します：

{
  "mcpServers": {
    "samarth-gtm-remote": {
      "command": "npx",
      "args": ["mcp-remote@next", "https://your-server.com/mcp"]
    }
  }
}

Vercel

制限事項：Vercel Serverless Functions のタイムアウトは10秒（hobby）／60秒（pro）です。状態を保持する SSE セッションには永続的な接続が必要ですが、Vercel はこの接続を十分にサポートしていません。Vercel はステートレスな MCP インタラクションにのみ使用してください。推奨される代替案：Vercel と外部セッションストア（Redis／Upstash）の組み合わせ、または代わりに Render／Fly.io を使用してください。

Vercel では、Express アプリをサーバーレスハンドラーとしてエクスポートします：

// api/mcp.ts
export default app; // where app is the Express instance

Vercel Dashboard → Settings → Environment Variables で環境変数を設定します。

Render

1. Render で新しい Web Service を作成します
2. GitHub リポジトリを接続します
3. ビルドコマンド：npm install && npm run build
4. 起動コマンド：GTM_MCP_TRANSPORT=http node dist/index.js
5. Render Dashboard で環境変数を追加します
6. 重要：RENDER=true 環境変数を設定し、ヘルスチェックが /health にアクセスするようにします

Render は永続的な長時間接続に対応しています。SSE／ストリーミングには Render を推奨します。

Fly.io

fly launch
fly secrets set GOOGLE_CLIENT_ID=xxx GOOGLE_CLIENT_SECRET=xxx GOOGLE_REFRESH_TOKEN=xxx
fly secrets set GTM_MCP_TRANSPORT=http GTM_MCP_HTTP_PORT=3001
fly deploy

Fly.io にはリクエストタイムアウトの制限がなく、永続的な WebSocket／SSE 接続に対応しています。本番環境での使用におすすめです。

Docker

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY dist/ ./dist/
ENV GTM_MCP_TRANSPORT=http
ENV GTM_MCP_HTTP_PORT=3001
EXPOSE 3001
CMD ["node", "dist/index.js"]

---

セキュリティに関する注意事項

1. .env は絶対にコミットしないでください — OAuth トークンが含まれています。.env はすでに .gitignore に登録されています。

2. トークンは定期的にローテーションしてください — OAuth リフレッシュトークンは有効期間が長いものの、取り消すことができます。myaccount.google.com/permissions で取り消してください。

3. スコープは最小限にしてください — 読み取りアクセスのみが必要な場合は、OAuth 同意画面から書き込みスコープを削除して再認証し、書き込みスコープを取り消してください。tagmanager.readonly のみでサーバーの読み取り機能を問題なく利用できます。

4. クラウドへのデプロイ：シークレットはプラットフォームのシークレットマネージャー（Render Secrets、Fly.io Secrets、Vercel Env Vars）に保存し、コードや Docker イメージには絶対に含めないでください。

5. HTTP トランスポート：/mcp には認証モードが組み込まれています。GTM_MCP_HTTP_AUTH_TOKEN（デプロイを識別する共通のベアラートークン）と STYTCH_PROJECT_ID（ユーザーごとの OAuth。各リクエストは、そのユーザー自身の Google 権限を使って処理されます）です。どちらも設定されていない場合、トランスポートは起動を拒否します。GTM_MCP_HTTP_ALLOW_UNAUTHENTICATED=true を設定すると、ローカル開発用にこの制限を解除できます。この場合、ループバックインターフェースのみにバインドされます。

6. 公開ガード：AI クライアントから明示的に公開する場合を除き、GTM_MCP_ENABLE_PUBLISH=false のままにしてください。本番環境に誤ったタグを公開する操作は、最もリスクが高い操作です。

7. 監査ログ：サーバーはすべてのセッションイベントを stderr に記録します。本番環境では、ログをロギングサービスに送信してください。

---

開発

# Install dependencies
npm install

# TypeScript type check (no emit)
npm run typecheck

# Build
npm run build

# Watch mode
npm run build:watch

# Run dev server (stdio, with hot-reload)
npm run dev

# Run HTTP dev server
npm run dev:http

# Tests (run `npm run build` first — some suites test the compiled dist)
npm test

# Smoke test: server boots and answers tools/list
npm run smoke -- --mcp dist/index.js

# Full-surface smoke test: invokes ALL registered tools with a sanitized,
# credential-free env — every handler must respond cleanly (no crash/hang)
npm run smoke:all

# MCP Inspector (interactive tool debugging)
npm run inspector

プロジェクト構成

samarth-gtm-mcp/
├── src/
│   ├── index.ts              # Entry point — stdio/HTTP transport setup
│   ├── server.ts             # MCP server factory + tool registration
│   ├── auth/
│   │   └── googleAuth.ts     # OAuth2 / service account auth
│   ├── tools/
│   │   ├── index.ts          # Tool registration aggregator
│   │   ├── accounts.ts       # accounts/list, accounts/get
│   │   ├── containers.ts     # containers/list/get/create
│   │   ├── workspaces.ts     # workspaces + sync/resolve_conflict
│   │   ├── tags.ts           # tags CRUD
│   │   ├── triggers.ts       # triggers CRUD
│   │   ├── variables.ts      # variables CRUD
│   │   ├── folders.ts        # folders CRUD + move_entities
│   │   ├── builtInVariables.ts # enable/disable/revert built-ins
│   │   ├── versions.ts       # versions list/get/create/publish/delete
│   │   ├── publish.ts        # quick_preview, versions_publish, create+publish
│   │   ├── audit.ts          # audit_container analytics checks
│   │   ├── export.ts         # export_container JSON dump
│   │   ├── environments.ts   # environments CRUD + reauthorize
│   │   ├── userPermissions.ts # account-level user permissions
│   │   ├── serverSide.ts     # clients, transformations, zones, templates, gtag config
│   │   ├── ga4Admin.ts       # read-only GA4 Admin tools (ga4_*)
│   │   └── ga4Data.ts        # read-only GA4 Data API reporting
│   ├── utils/
│   │   ├── guardrails.ts     # Guardrail enforcement, error formatting
│   │   ├── gtmClient.ts      # googleapis GTM v2 client factory
│   │   ├── ga4Client.ts      # GA4 Admin/Data client factories
│   │   ├── apiRetry.ts       # retry/backoff config (429/5xx, reads only)
│   │   ├── pagination.ts     # transparent nextPageToken following
│   │   ├── schemas.ts        # shared Zod input schemas
│   │   └── toolResponse.ts   # standard tool result shaping
│   ├── types/
│   │   ├── gtm.ts            # GTM API type definitions
│   │   └── index.ts
│   ├── scripts/
│   │   ├── auth-google.ts    # Browser-based OAuth onboarding (`npm run auth:google`)
│   │   └── oauth-setup.ts    # Interactive OAuth token helper (legacy paste-the-code flow)
│   └── __tests__/
│       ├── guardrails.node.test.mjs  # guardrails + buildPath
│       ├── auth.node.test.mjs        # env/auth resolution + token file paths
│       ├── pagination.node.test.mjs  # paginate/buildListResult
│       ├── ga4Admin.node.test.mjs    # GA4 tool registration (tests compiled dist)
│       └── apiRetry.node.test.mjs    # retry/backoff config (tests compiled dist)
├── scripts/
│   ├── smoke-test.mjs        # health probe: portal endpoints + MCP tools/list
│   └── smoke-all-tools.mjs   # invokes all tools with sanitized env
├── .env.example
├── .gitignore
├── package.json
├── tsconfig.json
└── README.md

---

リリース

リリースは semantic-release と GitHub Actions によって完全に自動化されています。main へのプッシュのたびに release.yml ワークフローが実行され、次の処理が行われます。

1. 依存関係をインストールし、型チェック、ビルド、テストを実行します。
2. Conventional Commits の仕様に基づいて、前回のタグ以降のコミットを確認します。
3. 次のセマンティックバージョン（MAJOR.MINOR.PATCH）を決定します。
4. CHANGELOG.md を更新し、package.json / package-lock.json の version を更新します。
5. chore(release): x.y.z [skip ci] でこれらのファイルを main にコミットします（[skip ci] マーカーはリリースの無限ループを防ぎます）。
6. Git タグ（vX.Y.Z）と、自動生成されたリリースノートを含む GitHub リリースを作成します。

このワークフローは組み込みの GITHUB_TOKEN を使用するため、追加のシークレットは必要ありません。npm publish は無効になっています。このパッケージは npm レジストリではなく、GitHub リポジトリとリリースを通じてバイナリとして配布されます。

Conventional Commit の例

コミットメッセージによってバージョンの更新内容が決まります。

コミットのプレフィックス	影響	例
fix:	パッチリリース（x.y.Z）	fix: handle empty workspace in audit tool
feat:	マイナーリリース（x.Y.0）	feat: add bulk tag import tool
perf:	パッチリリース	perf: cache GTM client between tool calls
docs: / chore: / refactor: / test: / style: / ci: / build:	リリースなし	docs: clarify OAuth setup steps
BREAKING CHANGE: フッター、またはタイプの後の !	メジャーリリース（X.0.0）	下記を参照

破壊的変更の例

feat!: drop support for Node.js 18

BREAKING CHANGE: minimum required Node version is now 20.

または：

refactor(auth): rename GOOGLE_REFRESH_TOKEN env var

BREAKING CHANGE: GOOGLE_REFRESH_TOKEN is now GTM_GOOGLE_REFRESH_TOKEN.
Update your .env file accordingly.

ローカルでのドライラン

公開せずに次のリリース内容を確認するには：

GITHUB_TOKEN=<a-token-with-no-perms-is-fine-for-dry-run> \
  npx semantic-release --dry-run --no-ci

手動でリリースをスキップする

リリースをトリガーせずにコミットを反映するには、リリース対象にならないタイプ（chore:、docs: など）を使うか、コミットの件名に [skip ci] を追加してください。

---

トラブルシューティング

「The caller does not have permission」（403）

• お使いの Google アカウントに、この GTM アカウントまたはコンテナへのアクセス権がない可能性があります
• サービスアカウントが GTM に追加されていません。サービスアカウントの制限を参照してください
• 同意画面で OAuth スコープを確認してください

「invalid_grant」または「Token has been expired or revoked」

• npm run auth:google を再実行して、トークンファイルを更新してください
• トークンを環境変数で管理する場合は、.env に GOOGLE_REFRESH_TOKEN を直接設定してください
• Google から refresh_token が返されない状態が続く場合は、myaccount.google.com/permissions で以前のアクセスを取り消し、認証スクリプトを再実行してください

「書き込み操作は無効です」

• .env に GTM_MCP_ENABLE_WRITES=true を設定してください
• サーバー／デスクトップアプリを再起動してください

Stdio サーバーから出力がない

• Stdio サーバーは意図的に stdout に何も出力しません（stdout は JSON-RPC チャネルです）
• 診断出力は stderr に送られます。ターミナルまたは Claude Desktop のログを確認してください

デスクトップアプリ：npm run dev で Error: Electron uninstall

• Electron バイナリはダウンロードされましたが、展開が完了していません。確実に再展開する方法については、apps/desktop/INSTALL.md を参照してください

googleapis の型に関する TypeScript エラー

• npm install を実行して、すべての依存関係がインストールされていることを確認してください
• googleapis パッケージには独自の型が含まれているため、@types/googleapis は不要です

---

TODO／既知の制限事項

• workspace_resolve_conflict：GTM API の resolve_conflict エンドポイントでは、エンティティの完全なボディが必要です。正確なリクエストボディのスキーマは複雑です。現在の実装では、ユーザー指定の JSON をそのまま渡すため、呼び出す前にエンティティの種類に照らして検証してください。
• containers_create：usageContext の列挙値は、GTM のリージョンやバージョンによって多少異なる場合があります。最新の許可値については、GTM API ドキュメントを参照してください。
• 単一 ID の HTTP 認証は共有シークレットです：GTM_MCP_HTTP_AUTH_TOKEN はすべてのクライアントに対して 1 つのベアラートークンで /mcp を保護するため、呼び出し元ではなくデプロイを識別します。ユーザーごとに ID を管理するには、STYTCH_PROJECT_ID を設定してマルチユーザーモードを有効にしてください。詳しくはセキュリティに関する注意事項を参照してください。
• HTTP セッションはメモリ内に保持されます：セッションはサーバープロセス内に保持されるため、水平スケーリングにはスティッキーセッションが必要です。単一チームのインスタンスには適していますが、複数インスタンスのロードバランシングにはまだ対応していません。
• デプロイごとに OAuth ID は 1 つ — 単一 ID モードのみ：STYTCH_PROJECT_ID を設定しない場合、すべてのリクエストで 1 つの Google ID を共有するため、Google API のクォータプールも 1 つになります。1 つのデプロイを通じて多数のユーザーが高負荷で利用すると、クォータを使い切ります。バックオフを伴う再試行で影響は和らぎますが、クォータの上限は解消されません。マルチユーザーモードでは各メンバーが自身の Google の認可とクォータを使うため、この問題を回避できます。

---

Samarth Analytics 制作 — Swapnil Jaykar、Sarthak Mandage