LoomaScale for Google Ads

google-ads-mcp

ChatGPT や Claude から、ホストするサーバー上で Google Ads アカウントを操作できます。パフォーマンスの確認、キーワード調査、キャンペーンの作成、予算の編集が可能です。支出ガードレールを設けることで、どのような説得をされても上限を超えられないようにします。

認証済みの MCP エンドポイントを通じて、42 個のツールを利用できます。MIT ライセンスです。2026 年から ChatGPT 内で実際のキャンペーンを運用してきた本番サービスから切り出されました。

問題点

LLM を Google Ads API に接続するのは、週末のプロジェクトのように聞こえるかもしれません。実際には、次のような問題があります。

落とし穴	問題点
デベロッパートークンのアクセスレベル	新しいトークンは テストアカウント アクセスで、テストアカウントにしか接続できません。最初の実行では空のリストが返り、壊れているように見えます。基本アクセスには申請が必要で、承認まで数日かかります
マネージャーアカウント	listAccessibleCustomers が返すのは主に MCC アカウントで、キャンペーンはありません。広告を運用するアカウントはその配下にあり、それぞれ、見つかったマネージャーを login-customer-id に設定して指定します
マイクロ単位	API は 100 万分の 1 単位で扱います。予算の 5000000 は通貨の 5 単位です。10⁶ 倍の誤りは、実際の支出事故につながります
通貨	金額に通貨情報は含まれません。UAH の予算を $ 付きで表示すると、ユーザーは実際の金額の 40 倍だと受け取ります
GAQL	SQL ではありません。JOIN はなく、セグメント化によって行の 意味 が変わります。誤ったセグメントを指定すると、合計がひそかに何倍にもなります
API バージョン	公開されたスケジュールに沿って廃止されます。固定したバージョンは非推奨になるのではなく、動作しなくなります
LLM は支出しようとします	キャンペーンの有効化、予算の引き上げ、または実際のキャンペーンを使った「ちょっとしたテスト」を提案します

このサーバーはこれらすべてに対処し、最後の項目はデフォルトで拒否します。

実行しないこと

クイックスタートの前にお読みください。金銭が関わります。

• 何も自動で公開されません。 google_create_campaign のスキーマにはステータスフィールドがないため、モデルは有効なキャンペーンを作成 できません。有効化には別のツールが必要です。
• このサーバーが作成したキャンペーンだけを、有効化できます。 Google Ads の UI で作成したキャンペーンは、予算が上限チェックを通過していないため拒否されます。
• 予算変更はすべて、アカウントの通貨で設定した上限と照合されます。 サーバーは要求を拒否し、上限に合わせて黙って切り下げることはありません。
• 書き込みツールには ツールごとの 1 日あたりの上限 があり、ループによって何百もの変更が行われるのを防ぎます。
• これとは別に、暴走ループ防止機能 があります。1 回の時間枠内に集中した呼び出しは拒否されます。
• ユーザーの識別は行いません。 初期設定は単一オペレーター用で、パスワードとアカウントはそれぞれ 1 つです。マルチユーザーのログインには対応していません。

クイックスタート

git clone https://github.com/loomascale/ads-mcp && cd ads-mcp
cp .env.example .env && $EDITOR .env      # every value is documented in place
docker compose up

次に http://localhost:8080/connections を開き、オペレーターのパスワードを入力して、Google Ads アカウントを接続します。

MCP_DEFAULT_MAX_DAILY_BUDGET_CENTS は低い値から始めてください。これはモデルとあなたのカードの間にある最後の安全策です。

前提条件

Google Ads のデベロッパートークン。 Google Ads マネージャー（MCC）アカウント → ツールと設定 → API センターに進みます。基本アクセスを申請してください。デフォルトはテストアカウントアクセスで、テストアカウントにしか接続できません。初回の実行がうまくいかない最も一般的な原因です。承認には数日かかるため、まず申請してください。

Google Cloud OAuth クライアント。 プロジェクトで Google Ads API を有効にし、認証情報 → OAuth クライアント ID → ウェブアプリケーションに進みます。認証済みのリダイレクト URI として http://localhost:8080/connect/google/callback を登録してください。少しでも異なると、Google は redirect_uri_mismatch で拒否します。

マネージャーアカウントを使う場合は？ 設定は不要です。接続フローで、アクセス可能な各顧客のツリーをたどり、マネージャーをスキップして、アカウントごとに正しい login-customer-id を記録します。

クライアントを接続する

ChatGPT と Claude には、末尾が /mcp の公開 HTTPS URL が必要です。クライアント自身を登録し、PKCE フローを進めて、同意画面に移動します。

どちらも localhost には接続しないため、試す前にトンネルを用意してください。

cloudflared tunnel --url http://localhost:8080

OAUTH_ISSUER にはトンネルの https オリジンを設定してください。クライアントはディスカバリードキュメントから issuer を読み取り、その値が示す接続先と通信するため、古い値のままだとクライアントのバグのように見える形で失敗します。

クライアントを使わずにデバッグするには：

curl -s -X POST https://your-host/mcp \
  -H 'Authorization: Bearer <token>' -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq '.result.tools[].name'

ツール

ツールは 42 個で、すべて google_ で始まります。読み取りツールには ads.read が必要です。書き込みツールには ads.write が必要で、さらに上記のガードレールを満たす必要があります。

アカウントと請求 — list_ad_accounts、check_billing、check_pacing、update_account_budget

キャンペーン — list_campaigns、create_campaign、create_pmax_campaign、activate_campaign、set_status、update_budget、update_campaign_bidding、update_campaign_settings、update_campaign_targeting、update_campaign_negatives、update_campaign_conversion_goals

広告グループと広告 — create_ad_group、update_ad_group、list_ads、create_ad、update_ad

キーワードと検索語句 — list_keywords、add_keywords、remove_keywords、update_keyword、list_search_terms、keyword_ideas

Performance Max — list_asset_groups、update_asset_group、update_asset_group_assets、update_asset_group_media、update_search_themes、update_brand_assets

サイトリンク — list_sitelinks、create_sitelinks、update_sitelink、remove_sitelinks

インサイト — get_insights、get_geo_insights、get_audience_insights、list_conversion_actions、update_conversion_action、find_locations

ライブラリとして使用する

API クライアントは、Google Ads との通信だけを必要とするコード向けに、Spring と MCP を含まない別パッケージとして公開されています。

<dependency>
  <groupId>com.loomascale</groupId>
  <artifactId>google-ads-client</artifactId>
  <version>0.1.0</version>
</dependency>

ツールとサーバーは google-ads-mcp で、mcp-core を基盤として構築されています。mcp-core はプロトコル層と OAuth 2.1 認可サーバーを提供します。認証情報、クォータ、ブランディング、同意、監査など、そこで利用できるすべての拡張ポイントは、Bean を宣言することで置き換えられます。

セキュリティ

認証情報は AES-256-GCM で保存時に暗号化されます。アクセストークンには、ほかの用途で署名に使うものとは別のキーが必要です。認可コードとリフレッシュトークンはハッシュ化して保存され、一度だけ使用できます。再利用されると、トークンファミリー全体が無効になります。モデルから渡された画像 URL は、サーバーが取得する前に SSRF ポリシーで検査されます。ツールの引数は記録されず、引数名だけが記録されます。

前段に TLS を設定してください。脆弱性は非公開で報告してください：SECURITY.md をご覧ください。

互換性

google-ads-mcp	mcp-core	Google Ads API	Java
0.1.x	0.1.x	v21	21+

このプロジェクトの由来

Google Ads 向け AI オペレーター、LoomaScale から切り出されました。ここにあるのは、本番環境で稼働しているものと同じ 42 個のツールです。縮小版ではありません。また、上記のガードレールは実際のアカウントを保護しているものです。

ホストしたくない場合は、ホスト型の製品を利用できます。開発者トークンの申請も OAuth クライアントも必要ありません。無料の Google Ads 無駄監査から利用を開始でき、プランは料金ページでご確認いただけます。セルフホストは単なるお試しではなく、実際の選択肢です。このリポジトリでは何も制限されていません。

どちらの方法を選ぶ場合も、クライアント側の手順は自分のサーバーに接続する場合と同じなので、次の 2 つのガイドを読むことをおすすめします： ChatGPT · Claude。

貢献

CONTRIBUTING.md をご覧ください。まずはシークレットのセクションから確認してください。

LoomaScale が本番環境で構築し、使用しています。MIT ライセンスです。