AdLoop

ヒント

AdLoop Cloud はこのプロジェクトのホスト版で、クレジットカード不要の無料プランがあります。 2回クリックするだけで Google に接続し、claude.ai、ChatGPT、Claude Code、Cursor、Gemini からすべてのツールセットを利用できます。Google Cloud プロジェクトも、API アクセスの申請も、OAuth の検証待ちも不要です。EU でホストされ、GDPR を最優先し、DPA も含まれています。

📚 ドキュメント：docs.getadloop.com — 各 AI クライアント向けのセットアップガイド、ツールセット、安全モデル、両エディションのトラブルシューティングをご覧いただけます。

---

Cloud とセルフホストのどちらを選びますか？

どちらのバージョンも、同じ安全モデルで同じツールを実行します。違いは、面倒な設定を誰が担うかです。

	☁️ AdLoop Cloud	🛠️ セルフホスト（このリポジトリ）
セットアップ	2回クリックして Google に接続	約5分：独自の Google Cloud プロジェクトを用意して adloop init を実行
Google Cloud プロジェクト	不要	必要（無料）
Ads API アクセス	不要	Cloud プロジェクトに付与（2026年9月以降、デベロッパートークンも MCC も不要）
対応環境	claude.ai、ChatGPT、Claude Code、Cursor、Gemini	Claude Code、Cursor、Claude Desktop、あらゆるローカル MCP クライアント
データの保存場所	EU サーバー（ドイツ）、GDPR を最優先し、DPA も含む	100％お使いのマシン上 — 外部に送信されません
アップデート	自動	pip install -U adloop
料金	カード不要の無料プラン。アカウント数や利用量を増やすには有料プランをご利用ください	永久無料（MIT）

迷ったら？Cloud から始めましょう — AdLoop の機能を最速で試せる方法であり、claude.ai や ChatGPT から AdLoop を使う唯一の方法です。すべてを自分のマシン上で管理したい場合や、コードを変更したい場合はセルフホストしてください。AdLoop 自体の開発に参加するためにここに来た方も、ようこそ。続きをご覧ください。

解決する課題

AdLoop は、コードと並行して Google Ads を管理するのが煩雑なために生まれました。AdLoop が解決する具体的な課題は次のとおりです。

• 「コンバージョンが減ったのに、原因がわかりません。」 AdLoop は、Ads のクリック数、GA4 のセッション数、コンバージョンイベントを1つのクエリで相互に照合します。ダッシュボードを1つずつ確認して何時間も浪費する前に、差が GDPR 同意の拒否、トラッキングの不具合、実際のランディングページの問題のどれによるものかを検出します。

• 「関連性のない検索に広告費を無駄遣いしています。」 検索語句レポートを取得して不要な語句を特定し、除外キーワードを追加できます。すべて IDE での1回の会話から実行できるため、Ads の UI に切り替える必要はありません。

• 「トラッキングは本当に機能していますか？」 実際のコードベースにあるイベント名と、GA4 が受信しているイベント名を比較します。不一致を見つけましょう。送信しているのに GA4 が認識していないイベントや、知らないうちに GA4 が記録しているイベントを特定できます。

• 「広告を作成したいのに、Google Ads の UI が使いにくいです。」 レスポンシブ検索広告の下書き作成、キャンペーンの作成、キーワードの追加などを、すべて自然言語で実行できます。変更内容はすべて、まずプレビューに表示されます。明示的に確認しない限り、変更が反映されることはありません。Claude、ChatGPT、VS Code ではプレビューが承認カードとして表示され、適用をクリックした場合にのみアカウントが変更されます（AI がボタンを押すことはできません）。新しい広告とキャンペーンは一時停止状態で作成されます。

• 「ランディングページに有料トラフィックはあるのに、誰もコンバージョンしません。」 AdLoop は広告の最終ページ URL と GA4 のページ単位データを結合します。クリックはあるのにコンバージョンがないページ、直帰率の高いページ、広告キャンペーンとの関連付けがないページを確認できます。

• 「すべてのページでコンバージョンにタグが設定されていますか？」 AdLoop は、稼働中の Google Tag Manager コンテナを読み取り、コードベース内のイベントや GA4 で発生しているイベントと照合します。そして、どのコンバージョンが取得されているか、どのタグが一時停止中か、どのページ範囲フィルターが狭すぎるか、どのコードベースのイベントにタグがないかを正確に知らせます。GTM Preview では1つの画面で確認できない、3つの情報源を照合する監査が可能です。

• 「EU の同意設定がデータ欠損の原因かどうかわかりません。」 欧州では、ユーザーの30～70％が分析用 Cookie を拒否します。AdLoop はこれを自動的に考慮するため、通常の GDPR 同意によるデータ欠損をトラッキングの不具合と誤診することはありません。

実際の利用から生まれました

すべてのツールは、実際の Google Ads キャンペーンを運用するなかで遭遇した問題をきっかけに生まれました。相互照合ツールがあるのは、「まず Ads のデータを取得し、次に GA4 のデータを取得して、両者を比較して」と AI に手動で頼み続けていたためです。そこで、データの結合を自動化しました。部分一致と手動 CPC の安全ルールがあるのは、AI がかつてまさにその組み合わせを作成し、予算を無駄にしたためです。GDPR 同意を考慮するのは、AI が EU での通常の Cookie 拒否をトラッキングの不具合と繰り返し誤診していたためです。

優れた機能は、実際のワークフローから生まれます。AdLoop を使っていて、できない操作をできるようにしたいと思ったら、状況を説明する issue を作成してください。「機能 X を追加して」だけでなく、「Y をしようとしたが、Z のためにできなかった」と説明してください。リクエストよりも背景が重要です。

すべてのツール

クイックスタート： pip install adloop または git clone https://github.com/kLOsk/adloop.git && cd adloop && uv sync && uv run adloop init を実行してください。または、AdLoop Cloud ならセットアップ不要です。

診断

ツール	機能
health_check	OAuth、GA4、Ads への接続を1回の呼び出しでテストします。問題がある場合は、対処方法を示すエラーメッセージも表示します。固定されている Google Ads API のバージョンも報告し、新しいバージョンが利用可能な場合は警告します。

GA4 読み取りツール

ツール	機能
get_account_summaries	GA4 アカウントとプロパティを一覧表示します
run_ga4_report	カスタムレポート：セッション、ユーザー、キーイベント、ページのパフォーマンス。ディメンションと指標によるフィルタリング、並べ替え、ページ分割、比較期間を任意で指定できます
run_realtime_report	リアルタイムデータ — デプロイ後にトラッキングが機能していることを確認します
get_tracking_events	設定済みのすべてのイベントとその発生数
list_key_events	プロパティのキーイベント（コンバージョン）。カウント方法、作成時刻、削除可能かどうかを確認できます
list_ga4_dimensions_and_metrics	プロパティでレポートに使用できるすべてのディメンションと指標。カスタムのものも含め、検索できます

Google Ads 読み取りツール

ツール	機能
list_accounts	アクセス可能な Ads アカウントを検出します
get_campaign_performance	キャンペーン指標：インプレッション数、クリック数、費用、コンバージョン数、CPA、検索インプレッションシェア、予算／ランクによるシェア損失
get_ad_performance	広告コピー分析：見出し、説明文、CTR、ポリシー承認状況、トピック
get_keyword_performance	キーワード：品質スコア、競合指標
get_search_terms	クリックする前にユーザーが実際に検索した語句
get_negative_keywords	キャンペーン単位の除外キーワードを一覧表示します
get_negative_keyword_lists	共有除外キーワードリスト（SharedSets）をすべて一覧表示します — 名前、ID、ステータス、キーワード数
get_negative_keyword_list_keywords	特定の共有除外キーワードリストに含まれるキーワードを一覧表示します
get_negative_keyword_list_campaigns	共有除外キーワードリストが適用されているキャンペーンを一覧表示します
get_recommendations	Google が自動生成した推奨事項：種類、推定効果、キャンペーンのコンテキスト
get_pmax_performance	ネットワーク別内訳とアセットグループの広告の有効性を含む、Performance Max キャンペーンの指標
get_pmax_assets	PMax のアセットごとの詳細：フィールドタイプ、配信状況、コンテンツ
get_asset_group_signals	PMax アセットグループの検索テーマとオーディエンスシグナル、および利用可能なオーディエンス
get_detailed_asset_performance	パフォーマンス上位のアセット組み合わせ：Google が最も多く選択する見出し＋説明文＋画像の組み合わせ
get_audience_performance	オーディエンスセグメントのパフォーマンス：リマーケティング、購買意向の強いユーザー、アフィニティ、デモグラフィック
get_shopping_product_performance	ショッピングと Performance Max における商品ごとの費用、コンバージョン数、CPA、ROAS、および費用が発生したもののコンバージョンに至らなかった商品
get_change_history	パフォーマンス低下前の変更内容：誰がいつ何を、どのクライアント（UI、API、スクリプト、自動適用された推奨事項）を通じて変更したか。過去30日間
get_demographic_targeting	広告グループまたはキャンペーンのデモグラフィック条件（年齢／性別／子どもの有無／収入）を一覧表示します
get_audience_lists	アカウントのリマーケティングリストと顧客リスト（規模、適格性、オープン／クローズ）、カスタムセグメントと組み合わせセグメント
search_audience_segments	Google の購買意向の強いユーザー向けセグメントとアフィニティセグメントを名前で検索します
get_audience_targeting	キャンペーンまたは広告グループのオーディエンスとオーディエンス除外、およびオーディエンスモード（モニタリングまたはターゲティング）
suggest_brands	ブランド名を Google が認識するブランドに照合します — ブランド ID、名前、状態、URL
check_brand_names	ブランド名の候補リストを Google のブランドナレッジグラフと照合します（1回の呼び出しにつき最大25件）
get_brand_lists	ブランドリスト（BRANDS タイプの SharedSets）を一覧表示します — ID、名前、ステータス、メンバー数
get_brand_list_brands	リスト内のブランドを、Commercial KG MID と削除用の条件 ID とともに一覧表示します
get_brand_list_campaigns	ブランドリストが適用されているキャンペーンと、それぞれの適用が除外かターゲティングかを表示します
get_ai_max_settings	キャンペーンと広告グループごとの AI Max 設定 — enable_ai_max、bundling_required、asset_automation_settings の全リスト、および各広告グループの disable_search_term_matching
get_campaign_settings	検索キャンペーンごとに1つのフラットなレコードを返します — ネットワーク、地域オプション、キャンペーン単位の部分一致、入札、予算、URL オプション、AI Max — リーチを拡大する設定にはフラグが付けられます
get_custom_conversion_goals	カスタムコンバージョン目標とそのアクション、および1つのキャンペーンの目標設定
run_gaql	その他のあらゆるデータを取得するための任意の GAQL クエリ

ブランドリスト — リストは BRANDS タイプの SharedSet です。キャンペーンに適用する際は、除外キーワードリストのような CampaignSharedSet ではなく、CampaignCriterion.brand_list を使用します（negative=true は除外、false は制限）。remove_from_brand_list と detach_brand_list_from_campaigns は実際に削除を行います — SharedCriterion にはステータスフィールドがありません。 ブランドターゲティング — ブランド条件（ブランドリスト、ブランドの除外）は、表示名ではなくブランドの Commercial Knowledge Graph ID をターゲットにします。単一の名前には suggest_brands、候補リストには check_brand_names を使って ID を取得します。exact_match は、大文字・小文字と句読点を除いて名前が一致する候補を示し、それ以外はすべて Google の候補です。

検索のブランド除外を適用するには AI Max が必要です — Google は、通常の検索キャンペーンにブランドリストを指定すると、「検索広告チャネルでは、ブランドリストは、ターゲティングの除外を目的とするキャンペーン、ターゲティングの対象に含めることを目的とする部分一致キャンペーン、または PMax 生成キャンペーンにのみ適用できます。」 として拒否します。draft_prepare_brand_exclusions は、Google に自動化を委ねることなく除外を利用できる状態を設定します。AI Max を有効にし、広告グループごとに検索語句とのマッチングを無効にし、テキストと最終ページ URL の自動化をオプトアウトします。状態の一部だけを変更する場合は、汎用的な draft_ai_max_settings を使います。これは、自動化が気付かれないまま有効になるようなプランを拒否し、自動化が明示的に要求されていた場合には、2 回目の確認を求めます。

カスタム コンバージョン目標 — キャンペーンに割り当てられる、名前付きのコンバージョン アクションのセットです。get_custom_conversion_goals は、アクションを含む目標と、キャンペーンの現在の目標設定を表示します。draft_custom_conversion_goal はセットを作成し、draft_update_custom_conversion_goal は名前を変更するか、そのアクションを置き換えます。draft_assign_custom_conversion_goal はキャンペーンにセットを割り当て、draft_clear_custom_conversion_goal はキャンペーンをアカウントレベルの目標に戻します。変更されるのは目標とキャンペーンの目標設定のみです。コンバージョン アクション、入札、予算はそのままです。

コンパクトモード — get_campaign_performance、get_keyword_performance、get_search_terms、get_ad_performance は compact=true を受け付けます。すべての行ではなく、アカウントの合計、内訳、上位 10 件の行、事前計算された問題項目のリスト（コンバージョンなしで費用が発生している項目、品質スコアの低いキーワード、除外キーワード候補、内容の乏しい RSA）を返します。レスポンスを約 90％削減できます。生の表で AI のコンテキストを埋め尽くすことなく、アカウントを監査できるように設計されています。

クロスリファレンスツール（GA4 + Ads の統合）

これらのツールは内部で両方の API を呼び出し、自動生成されたインサイトとともに統合された結果を返します。GA4 と Ads のツールを別々に使う場合との違いを生み出す、AdLoop の中核機能です。

ツール	機能
analyze_campaign_conversions	キャンペーンごとに Ads のクリック → GA4 のセッション → コンバージョンを対応付けます。GDPR の同意に関する欠落を検出し、実際の CPA を計算し、有料チャネルとオーガニックチャネルを比較します。
landing_page_analysis	広告の最終ページ URL と GA4 のページデータを結合します。ランディングページごとにコンバージョン率、直帰率、エンゲージメントを表示します。有料トラフィックがあるのにコンバージョンがゼロのページにフラグを付けます。
attribution_check	Ads が報告したコンバージョンと GA4 のイベントを比較します。差異の原因が GDPR の同意、アトリビューション期間、トラッキングの不具合のどれかを診断します。

トラッキングツール

ツール	機能
validate_tracking	コードベース内で見つかったイベント名を、GA4 で実際に記録されているイベント名と比較します。診断情報とともに、一致したイベント、不足しているイベント、想定外のイベントを返します。
generate_tracking_code	任意のイベントについて、そのまま貼り付けて使える GA4 gtag JavaScript を生成します。よく知られたイベント（sign_up、purchase など）に推奨パラメーターを設定でき、トリガー用のラッパーも任意で追加できます。

Google Tag Manager ツール

これらのツールは、実際の GTM コンテナを読み取り、コードベースおよび GA4 と照合して、GA4 の調査だけでは見つけられないトラッキングの欠落を特定します。たとえば、ページ単位のトリガー、一時停止中のタグ、動的なイベント名、壊れやすい CSS セレクター、タグがまったく設定されていないコードベース上のイベントなどです。

ツール	機能
audit_event_coverage	中心となるツールです。 コードベースのイベント ↔ GTM タグ ↔ GA4 での実際の発火を三者間で照合します。expected_events に含まれる各イベント名について、10 種類のステータス（ok、no_tag_no_fire、tag_paused、tag_active_but_not_firing、gtm_only_firing、ga4_only など）のいずれかと、欠落箇所に関する自動生成インサイトを返します。
list_gtm_accounts	アクセス可能な GTM アカウントを検索します
list_gtm_containers	アカウント配下のコンテナを一覧表示します。数値の container_id（ほかのツールで必要）、公開用の GTM-XXXXXXX ID、使用状況のコンテキスト（Web／iOS／Android／サーバー）を返します
list_gtm_tags	実際のコンテナ内のすべてのタグと、解析済みのイベント名および解決済みの発火／ブロックトリガー名を返します。workspace_id を指定すると、代わりにワークスペースの未公開状態を読み取れるため、作成したばかりのタグも確認できます（get_gtm_tag、list_gtm_triggers、get_gtm_trigger、list_gtm_variables でも同様です）
get_gtm_tag	単一タグの完全な生設定を返します。すべてのパラメーター、フィルター条件を含む発火／ブロックトリガー、優先度、一時停止状態、サンプリングを確認できます
list_gtm_triggers	フィルター条件を読みやすいテキスト（例：{{Page Path}} contains service-promotions、{{Form ID}} NOT contains wf-form-...）に解析した、すべてのトリガーを返します。negate フラグも明示的に表示します。
get_gtm_trigger	トリガーの完全な設定と、それを使用するすべてのタグの逆引き情報を返します。elementVisibility トリガーの解析済み element_visibility ブロック（セレクター、画面内に表示される割合、発火頻度）と、triggerGroup タイプの group_member_trigger_ids も含まれます
list_gtm_variables	カスタム変数（データレイヤー、定数、JS）と、有効になっている組み込み変数を返します
list_gtm_workspaces	コンテナ配下の下書き（ワークスペース）を一覧表示します。ワークスペース ID は get_gtm_workspace_diff で必要です
get_gtm_workspace_diff	下書き済みで未公開の変更を返します。「タグを編集したのに何も起きない」場合によくある原因です。保留中の変更がない場合は is_clean: true を返します。
list_gtm_versions	バージョン ID とエンティティ数を含むバージョン履歴を、新しい順に返します。Tag Manager API はバージョンのタイムスタンプや作成者を返しません。
get_gtm_version	単一の過去のコンテナバージョンについて、名前、メモ、タグ名、トリガー名を返します
get_gtm_version_diff	公開によって変更された内容を返します。追加、削除、変更されたタグ、トリガー、変数とその変更フィールドに加え、有効化または無効化された組み込み変数も含まれます。デフォルトでは、公開中のバージョンとその直前のバージョンを比較します。API 呼び出しは 2～3 回です。

GTM 書き込みツール（オプトイン）

デフォルトでは無効です。~/.adloop/config.yaml に gtm.write_enabled: true を設定して再起動すると、次回の呼び出し時に Tag Manager の編集および公開スコープへの再同意を求められます。これらのスコープがデフォルトの権限に含まれることはありません。すべての操作は通常どおり、下書き → プレビュー → confirm_and_apply の流れで行われ、タグとトリガーの編集は公開するまでワークスペースにのみ適用されます。

ツール	機能
draft_gtm_tag	タグを作成するか、tag_id を指定して更新します。更新は読み取り・変更・書き込みの手順で行われます。parameters はキー単位でマージされ、渡さなかったフィールド（優先度、同意設定、配信オプション、スケジュール、フォルダーなど）はすべて保持されます。タグタイプには、GTM の正式なテンプレート ID（googtag、gaawe、awct、sp、gclidw など）またはギャラリーテンプレートの cvt_<id> を指定します。
draft_gtm_trigger	トリガーを作成するか、trigger_id を指定して更新します（タイプは変更できません）。custom_event_name を指定すると、customEvent トリガーを dataLayer イベントに接続します。
draft_gtm_variable	GA4 の eコマース値用の Data Layer Variables など、変数を作成または更新します。参照されている変数の名前変更は拒否され、Custom JavaScript は制限されています。
draft_delete_gtm_entity	ワークスペース内のタグ、トリガー、または変数を削除します。使用中のトリガーと変数の削除は事前に拒否され、参照元が一覧表示されます。
draft_publish_gtm_workspace	ワークスペースを公開します。プレビューには、他のユーザーが GTM UI で行った編集も含め、保留中の変更がすべて表示されます。
draft_rollback_gtm_version	以前のコンテナバージョンを再公開します。プレビューには、公開中のバージョンから対象バージョンへの差分が表示されます。プランには公開中のバージョンが固定されるため、途中で他のユーザーが公開すると適用は拒否されます。ワークスペースはそのまま残ります。

GTM 固有の安全対策：

• カスタム HTML はサイト上で任意の JavaScript を実行するため、html タグを作成または編集する場合、あるいはそのタグを追加・変更するワークスペースを公開する場合は、gtm.allow_custom_html: true も設定されていない限り拒否されます。停止または削除は常に許可されます。
• 古い状態への書き込みはありません。 更新と削除ではプレビュー時のエンティティのフィンガープリントが固定され、公開ではワークスペースの保留中の変更が固定されます。その間に誰かがコンテナを編集すると、適用は拒否され、下書きを作り直す必要があります。
• マージ競合または GTM コンパイラーエラーがあると、公開は停止します。ドライランでは Tag Manager の クイックプレビュー が最初に実行されます（Tag Manager には検証のみを行うモードがないためです）。そのため、バージョンが作成される前にコンパイラーエラーを検出できます。このプレビューは POST リクエストであり、コンテナにプレビューバージョンを保存します。公開や公開中のタグへの変更は行われず、ドライランの残りの処理では読み取りのみを行います。
• 公開とロールバックの結果には、置き換えたバージョン（previous_live_version_id）が記載されるため、その ID を指定して draft_rollback_gtm_version を実行すれば、1 ステップでロールバックできます。バージョンは作成されたものの公開に失敗した場合、エラーには作成されたバージョン ID と、引き続き公開中のバージョン ID の両方が含まれます。
• safety.blocked_operations の操作別の名前：gtm_create_tag、gtm_update_tag、gtm_delete_tag、gtm_create_trigger、gtm_update_trigger、gtm_delete_trigger、gtm_publish_workspace、gtm_rollback_version。

Google アカウントには、Admin → User Management でコンテナの Edit 権限（公開する場合は Publish 権限も）が必要です。

GTM ツールのセットアップ — GCP プロジェクトで Tag Manager API v2 を有効にしてから、AdLoop 認証情報のメールアドレス（OAuth ユーザー、またはサービスアカウントを使用している場合はサービスアカウントのメールアドレス）を、Admin → User Management で GTM コンテナの Read ユーザーとして追加します。サービスアカウントのアクセス権は次回の呼び出し時に反映されます。以前の AdLoop バージョンからアップグレードする OAuth ユーザーは、一度だけ再認証が必要です。GTM スコープが新たに追加されたため、~/.adloop/token.json を削除して任意のツールを実行し、再同意してください。再同意するまでは、GTM ツールから権限エラーが返されます。

Search Console ツール

ツール	機能
list_gsc_sites	接続済みアカウントがアクセスできる Search Console プロパティを一覧表示します
run_gsc_report	オーガニック検索の分析：クエリ／ページ／国／デバイス／日付／検索での見え方／時間別のクリック数、表示回数、CTR、掲載順位を取得します。最新データ（data_state="all"）、aggregation_type、および start_row を指定して 25,000 行を超えるデータをページングする機能に対応しています

ウェブパフォーマンスツール

ツール	機能
analyze_page_speed	ランディングページの PageSpeed Insights：Lighthouse スコア、Core Web Vitals、実ユーザーの CrUX データ（ページのトラフィックが少なすぎる場合はサイト全体のデータにフォールバックし、その旨を表示）、主な改善点を取得します。OAuth は不要です（API キーは任意です）。

Merchant Center ツール

ツール	機能
list_merchant_accounts	アクセス可能な Merchant Center アカウントを確認します
get_merchant_feed_health	フィードの健全性 — レポートコンテキストごとの承認済み／保留中／不承認の件数、ドキュメントへのリンク付きの主な商品問題、アカウントレベルの問題を取得します。不承認の商品は通知なく Shopping／PMax への配信対象から外れます。
get_merchant_product_issues	フィードの健全性に関する件数の内訳となる商品を取得します。不承認、制限付き、保留中の商品と、各問題の属性および影響を受ける国を確認できます

Merchant Center ツールのセットアップ — GCP プロジェクトで Merchant API を有効にしてください（Content API for Shopping は非推奨です）。Merchant API には読み取り専用スコープがないため、AdLoop は読み取り専用で使用します。OAuth ユーザーをアップグレードするには、1 回再認証が必要です。

GSC ツールのセットアップ — GCP プロジェクトで Search Console API を有効にしてください。OAuth ユーザーをアップグレードするには、新しいスコープで 1 回再認証する必要があります（~/.adloop/token.json を削除して、任意のツールを実行してください）。強力な活用方法として、オーガニック検索クエリと get_keyword_performance を照合すると、有料検索とオーガニック検索のカニバリゼーションや、未開拓のキーワード機会を見つけられます。

Reddit 広告ツール

2 つ目の広告プラットフォームですが、安全モデルは同じです。Reddit は独立した接続で、専用の開発者アプリと OAuth を使用します。開発者トークンや承認プロセスは不要です。すべてのツールで ad_account_id を指定します（既定値は reddit.ad_account_id です）。

ツール	機能
list_reddit_accounts	ビジネスと広告アカウントを確認します（通貨、タイムゾーン、承認状態）
list_reddit_funding_instruments	請求方法と投稿プロフィールを確認します。キャンペーンや広告の作成に必要です
get_reddit_campaigns / get_reddit_ad_groups / get_reddit_ads	設定済みステータスと実効ステータス、予算、入札額、ピクセル、ターゲティング、週間スケジュール、却下理由を含む構成を確認します。include_copy を指定すると、各広告の投稿（見出し、本文、リンク先、メディア）を返します
get_reddit_performance	アカウント、キャンペーン、広告グループ、広告ごとの費用、クリック数、CTR、CPC、コンバージョン数、CPA、ROAS を確認します。任意の内訳（日付、国、コミュニティ、キーワード、掲載面など）や、インサイト付きのコンパクトモードも指定できます
run_reddit_report	あらゆる指標（リーチ、動画、イベントごとのコンバージョンなど）を取得する生のレポートエンドポイントを実行します
get_reddit_pixels	ピクセルと各イベントが最後に発生した日時を確認します。ピクセルから一度も送信されていないイベントに最適化する広告グループを通知します
get_reddit_audiences	ステータス、サイズ、ソースを含むカスタムオーディエンスと保存済みオーディエンス、および各オーディエンスをターゲットまたは除外している広告グループを確認します
search_reddit_targeting	コミュニティ、興味・関心、地域、言語、キーワード候補、Reddit による関連コミュニティの候補（シードとなるコミュニティまたはウェブサイトを指定）を検索します
get_reddit_account_history	誰が、いつ、何を変更したかを確認します。フィールド、変更前／変更後、メンバーを表示します
estimate_reddit_ad_group	作成予定の広告グループについて、オーディエンスサイズ、配信予測、推奨入札額の範囲を確認します（estimate_budget に相当する Reddit の機能です）
pause_reddit_entity / enable_reddit_entity / remove_reddit_entity	プレビューゲートを通じてステータスを変更します（削除は ARCHIVE で、取り消し不可、二重確認が必要です）
update_reddit_campaign / update_reddit_ad_group / update_reddit_ad	予算、入札額、掲載期間、週間スケジュール（曜日名、閲覧者の現地時間）、ターゲティング、掲載面、ターゲットまたは除外するオーディエンス（下書き時に Reddit で検証）、リンク先 URL、コメントを更新します。変更前 → 変更後のプレビュー、予算上限、入札額引き上げガードも含まれます
draft_reddit_campaign / draft_reddit_ad_group / draft_reddit_ad	キャンペーン → 広告グループ（ピクセルとターゲティングが必須）→ 投稿と広告（テキスト、画像、動画、または 2～6 枚のカードによるカルーセル、メディアは URL で指定）を作成します。または post_id を指定して既存の投稿を宣伝します。すべて PAUSED 状態で作成されます。
draft_reddit_custom_audience	ウェブサイト訪問者（ピクセルイベント）またはキャンペーンに反応したユーザーを対象とするリターゲティングオーディエンスを作成します。顧客リストのアップロードには対応していません。

Reddit 広告ツールのセットアップ — Reddit Ads Manager で Business Manager → Developer Application → Create app を開きます（ビジネス管理者のみ。承認待ちはありません）。リダイレクト URL を http://localhost:8765/callback と完全一致するように登録し、adloop init を実行して Reddit 広告の手順を完了します。この手順では Reddit の同意ページが開き（スコープは adsread と adsedit、許可は永続的）、リフレッシュトークンが ~/.adloop/reddit_token.json に保存され、既定の広告アカウントを選択できます。Reddit はユーザーごとにレート制限を適用し（レポートは 1 分あたり 60 リクエスト）、説明的な User-Agent を要求します。AdLoop はアプリ ID と Reddit のユーザー名を使ってこれを生成します。Reddit には検証のみのモードがないため、代わりに confirm_and_apply(dry_run=true) を実行すると、対象を再読み込みして安全上限を再確認します。

画像のアップロード

お使いのコンピューター上の画像や、チャットに添付した画像には公開 URL がないため、AI アプリからツールにファイルを渡すことはできません。upload_images を使うと、画像をアップロードできます。

ツール	機能
upload_images	MCP Apps 対応アプリではアップロードカードを表示します（最大 5 MB の PNG、JPEG、GIF をドロップできます）。それ以外のアプリでは AdLoop Cloud 上で 1 回限りのアップロードリンクを返します。このリンクはコーディングエージェントが curl -T で使用することもできます
list_uploads	まだ有効期限が切れていないアップロード（24 時間保持）の ID、寸法、サイズを一覧表示します

アップロード ID は draft_image_assets(upload_ids=[...]) に渡すか、AdLoop Cloud の draft_reddit_ad の画像フィールドに upload:<id> として指定します。

プランニングツール

ツール	機能
discover_keywords	シードキーワードや URL から新しいキーワード候補を見つけます。Google Ads Keyword Planner を使用した月別検索履歴と季節性の分析（include_monthly_volumes）を任意で含めることができます。月間平均検索数、競合レベル、ページ上部の入札額の範囲を返します。
estimate_budget	Google Ads Keyword Planner を使用して、キーワードセットのクリック数、費用、コンバージョン数を予測します。地域と言語のターゲティングに対応しています。キャンペーン開始前の予算計画に不可欠です。

Google Ads 書き込みツール

すべての書き込み操作は 下書き → プレビュー → 確認 のワークフローに従います。明示的な承認なしに実行されることはありません。

ツール	機能
draft_campaign	キャンペーンの構成一式を作成します。予算、キャンペーン（PAUSED）、広告グループ、およびオプションのキーワードが含まれます。検索パートナー、ディスプレイネットワークの拡張、MANUAL_CPC の初期広告グループ入札単価または TARGET_SPEND（クリック数の最大化）のクリック単価上限としての max_cpc に対応しています。
draft_shopping_campaign	リンク済みの Merchant Center フィード用に、標準ショッピング キャンペーンを作成します。予算、キャンペーン（PAUSED）、商品広告グループ、ショッピング広告、「すべての商品」グループを、1 回のアトミックなリクエストで作成します。手動クリック単価、クリック数の最大化、または目標広告費用対効果に対応しています。
draft_asset_group_assets	変更 1 回で、PMax アセットグループのアセット（テキスト、アップロードを含む画像、YouTube 動画）を追加・削除します。アセットを置き換えても、グループが Google の最小要件を下回ることはありません。
draft_asset_group_signals	検索テーマを追加するか、PMax アセットグループのオーディエンスシグナルを設定します。
draft_pmax_product_exclusions	商品 ID、ブランド、またはカスタムラベルを指定して、リテール向け PMax アセットグループから商品を除外します。
update_campaign	既存のキャンペーン設定（入札、予算、地域・言語ターゲティング、検索パートナー、ディスプレイネットワークの拡張、TARGET_SPEND（クリック数の最大化）の max_cpc 上限）を変更します。
draft_ad_group	既存のキャンペーン内に、一時停止状態の SEARCH_STANDARD 広告グループを作成します。MANUAL_CPC の max_cpc は任意で指定できます。
update_ad_group	広告グループ名や MANUAL_CPC の max_cpc を更新します。広告グループのステータス変更には pause_entity / enable_entity を使用してください。
draft_responsive_search_ad	RSA のプレビューを作成します（見出し 3～15 個、各 30 文字以内、説明文 2～4 個、各 90 文字以内）。見出しや説明文の数が推奨数を下回る場合に警告します。
draft_callouts	広告グループ、キャンペーン、またはアカウント用のコールアウト アセット（1～25 文字）を作成します。
draft_structured_snippets	公式のヘッダー値と 3～10 個の値を使用して、広告グループ、キャンペーン、またはアカウント用の構造化スニペット アセットを作成します。
draft_business_name_asset	広告に表示するビジネス名を、キャンペーンまたはアカウント用に作成します。
link_asset_to_customer	既存のアセットをアカウント全体にリンクします。アセットタイプはフィールドタイプと照合されます。
update_callout / update_sitelink / update_structured_snippet	アセットをその場で編集し、ID と履歴を保持します。プレビュー後に Google Ads で変更されていた場合、適用は拒否されます。
draft_call_asset / update_call_asset	広告グループ、キャンペーン、またはアカウント用の電話番号アセットを作成するか、その場で編集します。番号は解析され、国に応じて確認されます。
add_ad_schedule	キャンペーンに広告スケジュールの時間帯を追加します。重複する時間帯は拒否され、キャンペーンに初めてスケジュールを追加する場合は二重確認が必要です。
draft_promotion / update_promotion	プロモーション アセットを作成するか、渡されなかったフィールドを保持したままその場で編集します。金額はアカウントの通貨で指定します。
draft_price_asset	アカウントの通貨で、3～8 個の商品・サービスを含む価格アセットを作成します。
draft_image_assets	ローカルファイル、公開画像 URL、またはアップロードから、キャンペーン画像アセットを作成します（PNG、JPEG、GIF）。
draft_keywords	マッチタイプを指定してキーワードの追加を提案します。入札戦略を事前に確認し、スマート自動入札を使用していないキャンペーンで BROAD マッチを指定すると、プレビューで危険性を警告します。
add_negative_keywords	キャンペーンに除外キーワードを直接追加するよう提案します。
add_negative_locations	キャンペーンに地域の除外設定を追加するよう提案します。より広い地域をターゲットにしたまま、都市や地域を除外できます。
draft_key_event	GA4 イベントをキーイベント（コンバージョン）としてマークします。「イベントは発生するが、コンバージョンとして計測されない」問題を解決します。
draft_delete_key_event	GA4 のキーイベントを削除します。イベントの発生は継続しますが、今後のデータではコンバージョンとしてカウントされなくなります。
draft_demographic_targeting	年齢、性別、子供の有無、世帯収入のユーザー属性条件を提案します。デフォルトでは除外設定です。
draft_audience_attachment	オーディエンスをモニタリング（デフォルト）、ターゲティング（二重確認が必要）、または除外として追加します。Google が許可していない組み合わせや、ターゲティングには小さすぎる検索リストは拒否されます。
propose_negative_keyword_list	共有除外キーワードリスト（SharedSet）を作成し、キャンペーンに関連付けます。複数のキャンペーンで再利用できます。
propose_brand_list	Commercial KG MIDs からブランドリスト（タイプ BRANDS の SharedSet）を作成し、オプションでキャンペーンに関連付けます。negative=true（デフォルト）ではブランドを除外し、false ではターゲティングをそれらのブランドに限定します。
add_to_brand_list	既存のブランドリストへのブランド追加を提案します。
remove_from_brand_list	リストからブランドを削除するよう提案します（SharedCriteria にはステータスがないため、削除が唯一の方法です。二度目の確認が必要です）。
attach_brand_list_to_campaigns	既存のブランドリストを CampaignCriterion.brand_list としてキャンペーンに関連付けるよう提案します。
detach_brand_list_from_campaigns	キャンペーンからブランドリストを切り離すよう提案します（条件のみを削除し、リストは残します）。
draft_ai_max_settings	検索キャンペーンの AI Max 制御を作成します。enable_ai_max、広告グループごとの disable_search_term_matching、テキストと最終ページ URL のアセット自動作成（それぞれ OPTED_IN / OPTED_OUT / UNCHANGED）に対応しています。
draft_prepare_brand_exclusions	安全な標準状態を 1 ステップで作成します。AI Max を有効にし、削除されていないすべての広告グループで検索語句のマッチングを無効にして、テキストと最終ページ URL の自動作成をオプトアウトします。それ以外には変更を加えません。
draft_custom_conversion_goal	カスタム コンバージョン目標（名前付きのコンバージョン アクションのセット）を作成します。
draft_update_custom_conversion_goal	カスタム コンバージョン目標の名前を変更したり、アクションリストを置き換えたりします（リストを置き換えるもので、追加ではありません）。
draft_assign_custom_conversion_goal	キャンペーンでカスタム コンバージョン目標を指定します（goal_config_level = CAMPAIGN）。
draft_clear_custom_conversion_goal	キャンペーンをアカウント単位の目標に戻します（ロールバック）。
draft_dismiss_recommendations	適用しない Google のおすすめを非表示にし、再表示を防ぎます（Google は後で再表示することがあります）。
pause_entity	キャンペーン、広告グループ、広告、キーワード、または PMax アセットグループを一時停止します。
enable_entity	一時停止中のエンティティを再度有効にします。
remove_entity	エンティティを完全に削除します（取り消し不可のため、一時停止を推奨します）。キーワード、除外キーワード、広告、広告グループ、キャンペーンに対応しています。
confirm_and_apply	事前にプレビューした変更を実行します。

オーケストレーションルール

AdLoop には、これらのツールをどのように組み合わせるかを AI に教えるオーケストレーションルールが含まれています。マーケティングのワークフロー、GAQL の構文、安全プロトコル、GDPR への配慮、ベストプラクティスなどが盛り込まれています。ルールがなければ、AI はツールを使えても、その活用方法がわかりません。

• Cursor: .cursor/rules/adloop.mdc（正式なソース）
• Claude Code: .claude/rules/adloop.md（scripts/sync-rules.py を使って Cursor のルールから同期）

ルールには次の内容が含まれています。

• 一般的なワークフローのオーケストレーションパターン（パフォーマンスレビュー、コンバージョンの診断、キャンペーンの作成、除外キーワードの管理、キーワードの発見、トラッキングの検証、予算計画、ランディングページの分析）
• GAQL クイックリファレンス（構文、一般的なクエリ、注意点）
• 安全ルール（部分一致と手動 CPC の組み合わせの防止、書き込み前の検証など）
• 広告文の文字数制限に関するガイダンス（30 文字の見出しは、想像以上に短いものです）
• GDPR の同意に関する注意事項（EU 市場でトラッキングを誤診しないための配慮）

スラッシュコマンド（Claude Code）

AdLoop には、一般的なワークフロー用の定義済みスラッシュコマンドが .claude/commands/ に用意されています。

コマンド	機能
/analyze-performance	Google Ads と GA4 を対象とした包括的なパフォーマンスレビュー
/create-ad	安全チェックを行いながらレスポンシブ検索広告を作成
/diagnose-tracking	トラッキングとコンバージョンの問題を診断
/optimize-campaign	キャンペーン向けの包括的な最適化チェックリスト
/create-campaign	予算の見積もりを含めて新しい検索キャンペーンを作成
/budget-plan	キーワードプランナーを使ってキーワードの予算を見積もり

安全モデル

AdLoop は実際の広告費を扱うため、安全対策は必須です。

• 承認カード。 MCP Apps を表示できるアプリ（Claude、ChatGPT、VS Code など）では、変更のたびに「テスト実行」と「適用」を備えたカードが表示されます。適用するにはクリックが必要です。チャットで何を指示されていても、AI 自身による confirm_and_apply(dry_run=false) は APPROVE_ON_CARD で拒否されます。
• 確認ダイアログ。 カードには対応していないものの、エリシテーションに対応しているアプリ（たとえば Claude Code）では、実際の変更の前に AdLoop 自身がダイアログを表示します。AI はこれに回答できません。拒否しても変更は行われません。
• 2 段階書き込み。 変更操作はすべて、まずプレビューを返します。実行には別途 confirm_and_apply の呼び出しが必要です。
• デフォルトでドライラン。 confirm_and_apply でさえ、デフォルトは dry_run=true です。実際に変更するには、明示的に dry_run=false を指定する必要があります。
• 2 フェーズ適用（任意）。 safety.two_phase_apply: true を設定すると、計画でドライランを 1 回完了するまで、confirm_and_apply は dry_run=false を拒否します。プレビュー後に適用する手順が慣例ではなく、サーバーによって強制されます。
• 予算上限。 最大日予算を設定できます。上限を超える操作はサーバーが拒否します。
• 監査ログ。 ドライランも含め、すべての操作が ~/.adloop/audit.log に記録されます。
• 新しいキャンペーンと広告は一時停止状態です。 手動で有効化しない限り、配信されることはありません。
• 破壊的な操作には二重確認のフラグが付きます。 エンティティの削除や大幅な予算増額には追加の警告が表示され、AI には 2 回確認するよう指示されます。
• スマート自動入札を伴わない部分一致を検出します。 広告費を無駄にする最大の原因であるこの問題に対処するため、キャンペーンでスマート自動入札を使用していない場合、draft_campaign は部分一致キーワードを拒否します。また、draft_keywords／draft_ad_group はプレビューで該当キーワードを危険として示すため、適用前に AI が警告を出す必要があります。
• 書き込み前の検証。 書き込みの前に、AI が入札戦略、コンバージョン トラッキングの状態、品質スコアを確認します。キャンペーンに根本的な問題がある場合、AdLoop は状況を悪化させるのではなく、警告を表示します。
• 構造化されたエラー処理。 すべてのツールは、生の例外ではなく、対処方法のヒントを含む実用的なエラーメッセージを返します。認証エラーには、再認証の具体的な手順が含まれます。
• API バージョンの固定。 ライブラリ更新による予期しない破壊的変更を防ぐため、Google Ads API のバージョンを固定しています。新しいバージョンが利用可能になると、health_check が警告します。
• Ask モードとの互換性。 読み取りツールは readOnlyHint を宣言するため、Agent モードに切り替えずに Cursor の Ask モードで使用できます。

セットアップ

AdLoop は、OAuth にご自身の（無料の）Google Cloud プロジェクトを使用します。 adloop init ウィザードが手順を案内します。所要時間約 5 分の初回セットアップだけで、ユーザー数の共有上限も、誰かの審査完了を待つ必要もありません。AdLoop には組み込みの OAuth 認証情報は含まれていません。

セットアップを一切したくない場合は？ AdLoop Cloud はホスト版です。2 クリックで Google に接続でき、Cloud プロジェクトも API アクセス申請も不要で、EU でホストされています。

(組み込み認証情報を使用する ≤0.9 からアップグレードする場合：これらのサインイン方法は 0.10 で廃止されました。ご自身のプロジェクトに切り替えるには、adloop init を 1 回実行してください。)

重要

deleted_client: The OAuth client was deleted. または invalid_client が表示されますか？ AdLoop ≤0.9 の同梱認証情報が使用していた共有 Google Cloud プロジェクトは停止されたため、保存済みのサインイン情報を更新できなくなりました。今後の選択肢は 2 つです。AdLoop Cloud（2 クリックで Google に接続でき、設定不要）を利用するか、セルフホストを続ける場合は pip install -U adloop && adloop init を実行して、ご自身の無料の Google Cloud プロジェクトをセットアップしてください。詳細は固定された Issue（#49）をご覧ください。

インストール

PyPI から：

pip install adloop
adloop init

ソースから：

git clone https://github.com/kLOsk/adloop.git
cd adloop
uv sync
uv run adloop init

adloop init の処理内容

ウィザードでは、まず Google をセットアップするかどうかを尋ねます。Reddit Ads だけで AdLoop を実行する場合は「いいえ」と答えてください。手順 1〜6 をスキップし、Reddit の手順に進みます。それ以外の場合は、次の手順に沿って進みます。

1. Google Cloud のセットアップ — プロジェクトを作成し、3 つの API を有効にして、OAuth クライアントを生成します（ウィザードが案内する具体的な手順は、以下の カスタム Google Cloud プロジェクトのセットアップ を参照してください）。
2. Google Ads API のアクセス — Cloud プロジェクトの Google Ads API 概要ページで申請します。従来のデベロッパートークンの入力欄は空のままでかまいません。
3. MCC アカウント ID — マネージャー アカウント経由で複数のアカウントにアクセスする場合のみ必要です（任意）。
4. OAuth サインイン — ブラウザーを開いて Google にサインインします（ヘッドレスサーバーの場合は URL が表示されます）。
5. アカウントの自動検出 — GA4 プロパティと Ads アカウントを自動的に検出します。
6. 任意のサービス — GTM コンテナ、Search Console プロパティ（どちらも自動検出されます）、PageSpeed API キーを設定します。Enter キーを押せば、どれでもスキップできます。
7. Reddit Ads — Google と併用する場合は任意、Google を使わない場合は必須です。独自の Reddit 開発者アプリ、サインイン、デフォルトの広告アカウントが必要です。
8. 安全性のデフォルト設定 — 予算上限とドライランの設定です。
9. ツールセット — AI クライアントに表示するツールカタログの一部を選択できます（ツールセット を参照してください）。
10. エディター設定スニペット — 選択したツールセットを含む、Cursor と Claude Code の MCP 設定を表示します。

要件

• Python 3.11+
• Google Ads アカウント（マネージャー アカウントは任意です。1 回のログインで複数のアカウントにアクセスする場合にのみ必要です）
• Google Cloud プロジェクトでの Google Ads API アクセス（以下を参照してください）

Google Ads API のアクセス

2026 年 9 月 9 日以降、Google Ads API のアクセス権は、OAuth クライアントを所有する Google Cloud プロジェクトに付与されます。デベロッパートークンは廃止されました。API はこのヘッダーを無視するため、ウィザードでのトークン入力は任意であり、アクセス権を得るためにマネージャー アカウントが必要になることもありません。

Cloud Console で、プロジェクトの Google Ads API 概要ページから申請してください。

レベル	取得方法	利用可能な内容
テスト	Google Ads API を有効にすると自動的に適用されます	テストアカウントのみです。本番アカウントでは利用できません。CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION（古い API バージョンでは DEVELOPER_TOKEN_NOT_APPROVED）が表示された場合は、このレベルです。
エクスプローラー	「アクセスレベルをアップグレード」→ 申請。通常は自動的に承認されます	本番アカウントで 1 日あたり 2,880 オペレーションを利用できます。利用開始には十分です。
ベーシック	申請します。プロジェクトのブランド確認が完了し（OAuth 同意画面を「外部」に設定し、「本番環境で公開」した状態）、通常は数分以内に自動審査されます	1 日あたり 15,000 オペレーションを利用できます。
スタンダード	申請します。手動審査には約 10 営業日かかります	より高い上限を利用できます。Google の RMF ポリシーが適用されます。

Cloud の無料トライアル中のプロジェクト、または課金が無効になっているプロジェクトは、エクスプローラーとベーシックの申請が拒否されます。課金を設定したプロジェクトを使用してください。

CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION が表示されますか？ プロジェクトはテストレベルです。上記の概要ページを開き、エクスプローラーのアクセス権を申請してください。

ヘッドレスサーバー

ブラウザーのないサーバー（VM、Docker、SSH）で実行していますか？ ウィザードはこれを自動的に検出し、手動フローに切り替わります。任意のデバイスで開ける認証 URL が表示されるので、開いた後、リダイレクト URL をターミナルに貼り付けてください。

カスタム Google Cloud プロジェクトのセットアップ

ウィザードが案内する手順です。adloop init を実行する前に（または OAuth プロンプトで待機している間に）、ブラウザーで実施してください。

ステップ 1 — Google Cloud プロジェクト

1. console.cloud.google.com にアクセスして、新しいプロジェクトを作成します
2. 次の 3 つの API を有効にします（API ライブラリでそれぞれ検索してください）。
   • Google Analytics Data API — GA4 のレポートとイベント用
   • Google Analytics Admin API — GA4 プロパティの一覧表示用
   • Google Ads API — すべての広告関連操作用

ステップ 2 — OAuth 認証情報

1. Google Cloud プロジェクトで、APIs & Services → Credentials に移動します
2. Create Credentials → OAuth client ID をクリックします
3. アプリケーションの種類として Desktop app を選択し、任意の名前を付けます
4. JSON ファイルをダウンロードして、~/.adloop/credentials.json として保存します

サービスアカウントもサポートされています。サービスアカウントキーの JSON を同じ credentials_path に配置してください。AdLoop がファイルの種類を自動的に検出します。

ステップ 3 — エディターに接続する

Cursor — プロジェクトの .cursor/mcp.json に追加します。

{
  "mcpServers": {
    "adloop": {
      "command": "/absolute/path/to/adloop/.venv/bin/python",
      "args": ["-m", "adloop"]
    }
  }
}

続いて、このリポジトリの .cursor/rules/adloop.mdc をプロジェクトの .cursor/rules/ ディレクトリにコピーします。

Claude Code — 次を実行します。

claude mcp add --transport stdio adloop -- /absolute/path/to/adloop/.venv/bin/python -m adloop

または、プロジェクトの .mcp.json に追加します。

{
  "mcpServers": {
    "adloop": {
      "command": "/absolute/path/to/adloop/.venv/bin/python",
      "args": ["-m", "adloop"]
    }
  }
}

続いて、オーケストレーションルールとスラッシュコマンドをグローバルにインストールし、すべての Claude Code セッションで利用できるようにします。

adloop install-rules

これにより、~/.claude/CLAUDE.md に管理対象のブロックが書き込まれ、スラッシュコマンド（adloop-* という接頭辞付き）が ~/.claude/commands/ にコピーされます。ブロックは目印となるコメントで区切られているため、複数回実行しても安全です。再実行すると内容が更新されます。インストール方法は 2 種類あります。

• inline（install-rules のデフォルト） — ルール全体を ~/.claude/CLAUDE.md に埋め込みます。確実ですが、AdLoop に接続しているかどうかにかかわらず、すべてのリポジトリのすべての Claude Code セッションで読み込まれ、約 30K トークンを消費します。
• lazy（adloop install-rules --lazy。adloop init ではデフォルト） — CLAUDE.md に ~/.adloop/rules/adloop.md を参照する短い指示を記述します。LLM は AdLoop のツールが利用可能な場合にのみルールファイルを読み込むため、AdLoop を使わないセッションでは、ほとんどコストがかかりません。Claude Code は ~/.claude/rules/ 内のすべてのファイルをすべてのセッションで読み込むため、意図的にファイルを ~/.claude/ の外に配置します。

AdLoop のアップグレード後に更新するには、adloop update-rules を実行します。きれいに削除するには、adloop uninstall-rules を実行します。変更されるのは管理対象のブロックと adloop-* コマンドだけで、独自のコンテンツには手を加えません。

手動で管理する場合は、このリポジトリの .claude/rules/adloop.md と .claude/commands/ をプロジェクトの .claude/ ディレクトリにコピーしてください。

Claude Desktop / claude.ai には、プログラムからルールを設定する場所がありません。adloop install-rules を実行するとルールの内容が表示されるので、claude.ai の Project settings → Custom instructions に貼り付けてください。

使ってみる

AI アシスタントに、次のように尋ねてみましょう。

• 「今月の Google Ads キャンペーンの成果はどうですか？」
• 「予算を無駄にしている検索語句はどれですか？ 除外キーワードとして追加してください。」
• 「登録コンバージョンが減りました。GA4 と Ads を確認して原因を調べてください。」
• 「メインキャンペーン用の新しいレスポンシブ検索広告の案を作成してください。」
• 「有料トラフィックはあるものの、コンバージョンにつながっていないランディングページはどれですか？」
• 「トラッキングは正しく設定されていますか？ コードベースのイベントと GA4 を照合してください。」
• 「Google Tag Manager コンテナを監査してください。どのコンバージョンが計測されていて、どこに不足がありますか？」
• 「[product] で狙うべきキーワードは何ですか？ アイデアを探して、予算を見積もってください。」
• 「ドイツでこれらのキーワードを使う場合、必要な予算はいくらですか？」
• 「[product feature] の新しい検索キャンペーンを、1 日あたり €20 の予算で作成してください。」

設定リファレンス

すべての設定は ~/.adloop/config.yaml に保存されます。ドキュメント付きのテンプレートについては、config.yaml.example を参照してください。

セクション	キー	デフォルト	説明
google	project_id	(empty)	Google Cloud プロジェクト ID（カスタム認証情報を使用する場合のみ必要）
google	credentials_path	(empty)	OAuth クライアント JSON またはサービスアカウントキーのパス。空の場合は ~/.adloop/credentials.json を使用し、それ以外の場合は Application Default Credentials を使用します。
google	token_path	~/.adloop/token.json	OAuth トークンの保存先（自動作成）
ga4	property_id	—	GA4 プロパティ ID（adloop init が自動検出します）
ads	developer_token	—	レガシー項目（任意）：2026 年 9 月以降、API アクセスは Cloud プロジェクトに紐付けられています
ads	customer_id	—	デフォルトの Google Ads 顧客 ID（adloop init が自動検出します）
ads	login_customer_id	—	MCC アカウント ID
reddit	client_id / client_secret	(empty)	Reddit 開発者アプリ（Business Manager → Developer Application）
reddit	ad_account_id	(empty)	すべての Reddit ツールで使用するデフォルトの Reddit 広告アカウント（adloop init が選択します）
reddit	username	(empty)	Reddit のユーザー名。Reddit が要求する User-Agent でのみ使用します
reddit	token_path	~/.adloop/reddit_token.json	Reddit のリフレッシュトークンの保存先
safety	max_daily_budget	50.00	キャンペーンごとに許可される 1 日の最大予算
safety	require_dry_run	true	すべての書き込みをドライランモードに強制します
safety	two_phase_apply	false	プランがドライランを通過するまで、実際の適用を拒否します
safety	blocked_operations	[]	完全にブロックする操作

ツールセット — コンテキストの使用量を削減する

ほとんどの MCP クライアント（claude.ai、ChatGPT、Cursor など）は、会話を始めるたびにすべてのツールスキーマをモデルのコンテキストに読み込みます。AdLoop の全カタログでは、入力を始める前からコンテキストウィンドウのかなりの部分を占め、その分の料金が発生します。AdLoop の一部だけを使用する場合は、MCP クライアントの env ブロックで ADLOOP_TOOLSETS 環境変数を設定して、公開するツールを絞り込めます（adloop init ウィザードでも設定でき、スニペットに書き込まれます）。

"env": { "ADLOOP_TOOLSETS": "ads,ga4" }

ツールセット	対象
ads	Google Ads の読み取り、書き込み、プランニング（Keyword Planner）
ga4	Google Analytics のレポート、リアルタイムデータ、キーイベント
tracking	クロスチャネルアトリビューションとトラッキングコードの生成
gtm	Google Tag Manager の監査、読み取り、オプトインによる書き込み
gsc	Search Console の読み取り
web	PageSpeed / Core Web Vitals
merchant	Merchant Center のフィードの健全性
reddit	Reddit Ads の読み取り、書き込み、プランニング

Google Ads はさらに絞り込めます。ads の代わりに、以下のいずれかを使用してください。

サブセット	対象
ads:read	Ads レポート、GAQL、Ads/Analytics のクロスチェック（attribution_check、analyze_campaign_conversions、landing_page_analysis）
ads:write	Ads の下書きと変更。下書きには先に読み取り（ID、入札戦略）が必要なため、ads:read も有効になります
ads:plan	キーワード候補と予算予測（discover_keywords、estimate_budget）

health_check と confirm_and_apply は、選択内容にかかわらず常に含まれます。未設定の場合は全カタログが使用されます。無効な名前を指定すると、起動時に有効な名前の一覧とともにエラーになります。効果は明確です。監査や診断での ads:read,ga4 のコストは ads,ga4 の約 40％で、キーワード調査に特化した ads:plan のみのクライアントでは、全カタログの約 5％で済みます。ツールセットはインストール単位ではなく、クライアント単位です。1 つの AdLoop 設定を使って、絞り込んだ Cursor と全カタログの Claude Code を並行して利用できます。

AdLoop Cloud では、同じ機能を API キー単位で利用できます。ダッシュボードでキーを作成するときにツールセットを選択すると、そのキーの tools/list がサーバー側で絞り込まれ、どの AI クライアントで使用しても選択したツールだけが表示されます。

プロジェクト構成

src/adloop/
├── __init__.py        # Entry point — routes 'adloop init' to wizard, otherwise starts MCP server
├── server.py          # FastMCP server — every tool registration with safety annotations and toolset tags
├── config.py          # Config loader (~/.adloop/config.yaml)
├── auth.py            # OAuth 2.0 flow (user-supplied credentials, headless fallback) + service accounts; GA4 / Ads / GTM scopes
├── cli.py             # Interactive 'adloop init' setup wizard
├── crossref.py        # Cross-reference tools (GA4 + Ads + GTM combined analysis)
├── tracking.py        # Tracking validation + code generation tools
├── ga4/
│   ├── client.py      # GA4 Data + Admin API clients
│   ├── reports.py     # Account summaries, reports, realtime
│   └── tracking.py    # Event discovery
├── ads/
│   ├── client.py      # Google Ads API client (version-pinned) + retry/backoff for rate limits
│   ├── gaql.py        # GAQL query execution with human-readable error parsing
│   ├── read.py        # Campaign, ad, keyword, search term, negative keyword, shared sets, recommendations, audience reads
│   ├── pmax.py        # Performance Max tools — campaign/asset group performance, asset labels, top combinations
│   ├── write.py       # Draft campaign, RSA, keywords; pause, enable, remove, confirm
│   └── forecast.py    # Budget estimation + keyword discovery via Keyword Planner API
├── gtm/
│   ├── client.py      # Google Tag Manager API v2 client
│   └── read.py        # Live container fetching, tag/trigger/variable parsing, workspace diff, version history
├── reddit/
│   ├── auth.py        # Reddit OAuth2 (own app, permanent refresh token, loopback flow for adloop init)
│   ├── client.py      # Reddit Ads API v3 REST client — bearer refresh, per-user rate limits, pagination
│   ├── read.py        # Accounts, campaigns, ad groups, ads, performance reports, pixels, targeting lookups
│   └── write.py       # Draft/preflight/apply for status, budget, bid, targeting, and PAUSED creation
└── safety/
    ├── guards.py      # Budget caps, bid limits, blocked operations, Broad Match safety
    ├── preview.py     # Change plans and previews
    └── audit.py       # Mutation audit logging

ロードマップ

リリース済みの機能と今後の予定：

• GA4 の読み取りツール ✓
• 安全レイヤーを備えた Google Ads の読み取り・書き込みツール ✓
• クロスリファレンスインテリジェンス（キャンペーン→コンバージョンのマッピング、ランディングページ分析、アトリビューション比較） ✓
• トラッキングユーティリティ（GA4 に対するイベントの検証、gtag コードの生成） ✓
• Keyword Planner による予算の見積もりとキーワードの発見 ✓
• 共有除外キーワードリスト（SharedSet API） ✓
• API のレート制限に対するリトライ／バックオフ ✓
• セットアップウィザード（adloop init） ✓
• Claude Code のサポート ✓ — CLAUDE.md、.mcp.json、.claude/rules/、.claude/commands/、CLI ウィザードのスニペット
• Claude Desktop のワンクリックインストール — adloop install claude-desktop（および／または .dxt 拡張バンドル）で、AdLoop の MCP エントリを claude_desktop_config.json に自動的に書き込みます。これにより、Claude Desktop と Cowork のユーザーが JSON を手動で編集する必要がなくなります
• PyPI パッケージ ✓ — pip install adloop
• AdLoop Cloud ✓ — ホスト版です。Google Cloud プロジェクトも API 利用申請も不要で、2 回のクリックで Google に接続できます（EU ホスティング、GDPR を最優先）
• ヘッドレスサーバーのサポート ✓ — ブラウザーのないサーバー向けの、URL を手動でコピー＆ペーストするフロー
• 動作評価スイート ✓ — 読み取り、書き込み、トラッキング、プランニングのワークフローを対象とした、tests/evals/ 内のプロンプトと期待値によるテスト
• Google Tag Manager との連携 ✓ — タグ、トリガー、変数、ワークスペース、バージョン履歴の読み取りツールに加え、コードベースのイベント、GTM タグ、GA4 の実際の発火をまたぐ 3 方向結合を行う audit_event_coverage
• コミュニティでの公開 — HN、Indie Hackers、r/cursor、Twitter
• 動画による紹介

コントリビューション

ガイドラインについてはCONTRIBUTING.mdをご覧ください。簡単に言うと、まずご自身の状況を説明する Issue を作成し、機能を実装したい場合は、その後 PR を提出してください。

ライセンス

MIT — LICENSEをご覧ください。

プライバシー

オープンソース版はすべてお使いのマシン上で動作します。データが収集、保存されたり、サーバーに送信されたりすることはありません。プライバシーポリシーの全文はPRIVACY.mdをご覧ください。AdLoop Cloud には独自のプライバシーポリシーとDPAがあります。

---