mcpField
G
google-ads

google-ads

github.com/acedatacloudマーケティング・グロース17169 回インストール今日更新
リポジトリ

google-ads について

curl と jq で Google Ads API を照会するコマンドラインスキルです。アカウントの確認や GAQL レポートに対応し、OAuth と開発者トークンを使ってキャンペーン、広告グループ、キーワード、顧客データを取得します。

主な機能

  1. 01アクセス可能な顧客アカウントの一覧表示
  2. 02searchStream による GAQL レポート実行
  3. 03キャンペーンと広告グループの照会
  4. 04キーワードと顧客指標の取得
  5. 05マネージャーアカウントのコンテキスト処理

活用シーン

  1. 01OAuthユーザーが使えるアカウントの確認
  2. 02キャンペーン費用、クリック、コンバージョンの確認
  3. 03広告グループとキーワードの調査
  4. 04マネージャーアカウントでのレポート実行

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/acedatacloud/skills --skill google-ads

インストール後、Claude Code で/google-adsを入力して読み込まれたか確認します。

詳細

curl + jq を使ってGoogle Ads APIにクエリします。2 つの認証情報と 1 つのコンテキストヘッダーが必要です。

  • $GOOGLE_ADS_TOKEN — ユーザーの OAuth ベアラー（adwords スコープ）→ Authorization: Bearer $GOOGLE_ADS_TOKEN
  • $GOOGLE_ADS_DEVELOPER_TOKEN — プラットフォームのデベロッパートークン（サーバー側で注入）→ ヘッダー developer-token: $GOOGLE_ADS_DEVELOPER_TOKEN
  • login-customer-id — マネージャー（MCC）スコープの呼び出しでのみ必要です。リクエストの実行に使うマネージャー ID、または設定されている場合は $GOOGLE_ADS_LOGIN_CUSTOMER_ID を指定します（数字のみ、ハイフンなし）。customers:listAccessibleCustomers では不要です。

API バージョン： ベース URL は https://googleads.googleapis.com/<vNN> です。Google は約 4 か月ごとに新しい vNN をリリースし、古いバージョンを廃止するため、バージョンをハードコードすると、いずれ動作しなくなります。この例では v25 を使っています（2026-07 時点でサポート対象）。すべての呼び出しが 404 を返す場合、そのバージョンは利用できません。廃止済みか、まだリリースされていない可能性があります。customers:listAccessibleCustomers を試してください。サポート対象のバージョンは 401／200 を返し、利用できないバージョンは 404 を返します。例で使われているバージョンから 1 つずつ下げて試し、新しい vNN が存在すると決めつける前に、Google のサポート対象バージョン一覧を確認してください。

$GOOGLE_ADS_DEVELOPER_TOKEN が空の場合、コネクターの設定が完了していません。API を呼び出さず、その旨を伝えてください（呼び出すと 401／DEVELOPER_TOKEN_NOT_APPROVED が返されます）。

VER="v25"; BASE="https://googleads.googleapis.com/$VER"
AUTH="Authorization: Bearer $GOOGLE_ADS_TOKEN"; DEV="developer-token: $GOOGLE_ADS_DEVELOPER_TOKEN"
# Customers the OAuth user can access (ids are returned as customers/<id>)
curl -sS -H "$AUTH" -H "$DEV" "$BASE/customers:listAccessibleCustomers" | jq '.resourceNames'

GAQL（searchStream）でレポートする

CID="1234567890"   # target customer id, digits only
# Manager (MCC) access → send login-customer-id; direct access → drop the header.
# Array, not a plain string: the header value contains a space and would split.
LOGIN=(); [ -n "$GOOGLE_ADS_LOGIN_CUSTOMER_ID" ] && LOGIN=(-H "login-customer-id: $GOOGLE_ADS_LOGIN_CUSTOMER_ID")
curl -sS -H "$AUTH" -H "$DEV" "${LOGIN[@]}" \
  -H "Content-Type: application/json" -d '{
  "query":"SELECT campaign.name, metrics.cost_micros, metrics.clicks, metrics.conversions FROM campaign WHERE segments.date DURING LAST_30_DAYS ORDER BY metrics.cost_micros DESC"
}' "$BASE/customers/$CID/googleAds:searchStream" \
  | jq '.[].results[]? | {campaign: .campaign.name, cost_usd: (.metrics.costMicros|tonumber/1e6), clicks: .metrics.clicks, conv: .metrics.conversions}'

GAQL リソース：campaign、ad_group、ad_group_criterion（キーワード）、customer。費用は metrics.cost_micros です（÷ 1,000,000 でアカウント通貨に換算）。

注意点

  • すべてのエンドポイントで 404 が返る場合は、認証情報ではなく VER が原因です — バージョンが廃止済みか、まだリリースされていません。個別の呼び出しで 404 が返る場合は、その呼び出しに問題があります。リソースが見つからない（顧客 ID が不正）か、パスが間違っている可能性があります。認証をデバッグする前に、customers:listAccessibleCustomers でバージョンが有効か確認してください。
  • 2 つの認証情報と 1 つのコンテキストヘッダーが必要です。 すべての呼び出しで developer-token が必須です。login-customer-id が必要なのは、マネージャー（MCC）アカウントとして操作する場合のみです。customers:listAccessibleCustomers はこのヘッダーなしで動作します。マネージャースコープの呼び出しでこれを省略すると、ここで 401／403 が発生する主な原因になります。
  • 顧客 ID は URL／ヘッダーで数字のみにしてください（123-456-7890 のハイフンを削除します）。
  • searchStream は、それぞれに .results[] を含むチャンクの配列を返します。.[].results[]? でフラット化してください。
  • 費用はアカウント通貨のマイクロ単位です。1e6 で割ってください。

コメント

Markdown 対応