Google Ads MCP

Google Ads MCP

Google Ads API 用の読み取り専用 MCP サーバーです。11 個のツールで、探索、GAQL レポート、リソーススキーマ、推奨事項、キーワードプランニングと予測、およびマネージャーアカウント（MCC）配下でアクセス可能なアカウントの変更履歴を扱います。このサーバーは、すべての広告クライアント向けに本番環境で運用しています。読み取り専用は、変更・適用サービスのインポートを行わないこと、SDK メソッドの許可リスト、GAQL が SELECT で始まることを確認するガードの 3 層で徹底しています。

インストール

Claude Code：

claude mcp add google-ads \
  -e GOOGLE_ADS_DEVELOPER_TOKEN=your-token \
  -e GOOGLE_ADS_CLIENT_ID=your-client-id \
  -e GOOGLE_ADS_CLIENT_SECRET=your-client-secret \
  -e GOOGLE_ADS_REFRESH_TOKEN=your-refresh-token \
  -e GOOGLE_ADS_LOGIN_CUSTOMER_ID=1234567890 \
  -- uvx scalably-google-ads-mcp

Codex：

codex mcp add google-ads \
  --env GOOGLE_ADS_DEVELOPER_TOKEN=your-token \
  --env GOOGLE_ADS_CLIENT_ID=your-client-id \
  --env GOOGLE_ADS_CLIENT_SECRET=your-client-secret \
  --env GOOGLE_ADS_REFRESH_TOKEN=your-refresh-token \
  --env GOOGLE_ADS_LOGIN_CUSTOMER_ID=1234567890 \
  -- uvx scalably-google-ads-mcp

Claude Desktop：最新の GitHub リリースから google-ads-mcp.mcpb をダウンロードして開きます。

セットアップ

このギャラリーの中でもセットアップが最も大変です。開発者トークンの承認待ちに最大 2 日かかる場合があります。マネージャーアカウント（MCC）を起点とする 1 組の認証情報で、その配下にリンクされた任意の顧客アカウントを読み取れます。そのため、アカウントを MCC にリンクすれば、クライアントごとの設定は不要です。

1. Google Ads 開発者トークン。 マネージャーアカウントで ads.google.com にサインインし、［ツールと設定］から［API センター］に移動して、開発者トークンを申請します。新しいトークンにはまず Explorer アクセスレベルが付与されます。これは数日かかることのある審査の後に Google が付与するもので、探索、クエリ、推奨事項のツールを利用できます。より高いクォータには Basic アクセス（別途申請）が必要で、キーワードプランニングツールにも必要となる場合があります。
2. Google Cloud OAuth クライアント。 Google Cloud プロジェクトで Google Ads API を有効にし、［API とサービス］の［認証情報］から、種類が Desktop app の OAuth クライアント ID を作成します。クライアント ID とクライアントシークレットを控え、OAuth 同意画面に https://www.googleapis.com/auth/adwords スコープを追加します。
3. リフレッシュトークン。 マネージャーアカウントの管理者ユーザーとして、Google の oauth2l ツール、または google-ads Python ライブラリに付属する generate_user_credentials.py の例を使い、リフレッシュトークンを一度生成します。リフレッシュトークンを保存してください。通常の使用では有効期限が切れません。
4. ログイン顧客 ID。 マネージャーアカウント自体の 10 桁の顧客 ID（ハイフンなし）を GOOGLE_ADS_LOGIN_CUSTOMER_ID として使用します。クライアントアカウントは、自身の Google Ads UI から招待を承諾してこのマネージャーアカウントにリンクできます。その後、google_ads_list_customer_clients で確認できるようになります。

ツール（11）

ツール	機能
google_ads_list_accessible_customers	OAuth ユーザーが直接アクセスできるすべての customer_id を一覧表示します
google_ads_list_customer_clients	MCC 階層をたどり、すべての子アカウントを返します
google_ads_query	特定の顧客アカウントに対して GAQL クエリを実行します
google_ads_describe_resource	GAQL リソースのスキーマ（フィールド、指標、セグメント）を返します
google_ads_list_resources	GAQL リソースのカタログ全体を返します
google_ads_recommendations	顧客アカウントに対する Google の最適化の推奨事項を読み取ります
google_ads_keyword_ideas	検索ボリューム、競合度、CPC の推定値とともにキーワード案を生成します
google_ads_keyword_historical_metrics	特定のキーワードについて、過去の月間検索ボリュームと競合度の指標を返します
google_ads_keyword_forecast_metrics	提案されたキーワードプランの KPI を予測します
google_ads_change_events	過去 30 日間に誰が何を変更したかの監査記録を返します
google_ads_change_status	リソースごとの簡易な最終変更トラッカーです

設定

変数	必須	用途
GOOGLE_ADS_DEVELOPER_TOKEN	はい	Ads API Center から取得した Google Ads API のデベロッパートークン
GOOGLE_ADS_CLIENT_ID	はい	デスクトップアプリの認証情報用 OAuth2 client_id
GOOGLE_ADS_CLIENT_SECRET	はい	client_id と対になる OAuth2 client_secret
GOOGLE_ADS_REFRESH_TOKEN	はい	adwords スコープ用の長期間有効な OAuth2 refresh_token
GOOGLE_ADS_LOGIN_CUSTOMER_ID	はい	ハイフンなしの、マネージャーアカウント（MCC）の10桁の顧客 ID
GOOGLE_ADS_API_VERSION	いいえ	使用する Google Ads API のバージョン。デフォルトは v25
GOOGLE_ADS_USE_PROTO_PLUS	いいえ	proto-plus メッセージタイプを使用するかどうか。デフォルトは true
GOOGLE_ADS_LOG_LEVEL	いいえ	Python のログレベル。デフォルトは WARNING

応答形式

各ツールは、status（succeeded、partial、no_op）、operation、summary、target、result、proof、warnings、recoveryを含む JSON を返します。失敗した場合は、google_ads_request_failed: <message> <hint>というテキストのツールエラーが返されます。proof.apiVersionには使用した Google Ads API のバージョンが記録されます。proof.microsConvertedはgoogle_ads_queryで設定されます。partialステータスは、結果が設定された上限（max_rows、page_size、またはlimit）に達したことを意味します。続行方法はrecovery.nextActionに記載されます。

制限事項

google_ads_queryの応答は、Google Ads API により1回の呼び出しにつき64 MBに制限されています。大きな日付範囲は複数回に分けて呼び出してください。KeywordPlanIdeaService（キーワード候補、過去の指標、予測）は1秒あたり1クエリにレート制限されており、Explorer ティアで権限エラーが発生した場合は Basic Access が必要になることがあります。google_ads_change_eventsが対象とするのは過去30日まで、google_ads_change_statusが対象とするのは過去14日までです。metrics.cost_microsなどの*_microsフィールドは、1単位が$0.000001です。convert_microsが true（デフォルト）の場合、google_ads_queryは対応する*_unitsフィールドも併せて出力します。

検証

各リリースでは、パッケージのバージョン、.mcpbの sha256、およびビルド元となった本番環境のコミットを CHANGELOG.md に記載しています。CI では、プッシュのたびにテストと、ビルドした wheel のクリーンインストールを実行します。

プライバシーポリシー

このサーバーは、お使いのマシン上で、ご自身の認証情報を使ってローカルに動作します。個人データを収集せず、テレメトリーも含まず、データを永続的に保存せず、ラップするベンダー API とのみ通信します。Scalably を含め、第三者がデータを受け取ることはありません。お問い合わせ先：[email protected]。正式版：https://scalably.io/connector-privacy.html

ライセンス

MIT。Copyright Scalably。