google-ads

MCP Google Ads サーバー

変更を本番環境に反映する前にレビューできるよう、保護機能を組み込んだ Google Ads API 用の MCP（Model Context Protocol）サーバーです。MCC（管理者アカウント）に対応し、キャンペーン管理、レポート、最適化のための36個のツールを備え、実運用での実績があります。v1.2.0では、Demand Gen キャンペーンの作成に最初から最後まで対応しました。

機能

• MCC 対応：管理者アカウントと複数のクライアントアカウントで動作します
• コンテキストの自動判定：作業ディレクトリに基づいてクライアントアカウントを検出します
• デフォルトで安全：新しく作成されるすべての項目は一時停止状態になります
• 承認ワークフロー：手動レビュー後にのみ項目を有効化します
• 検証：広告の作成前に検証し、早期にエラーを検出します
• 高い回復性：サーキットブレーカー、バックオフ付き再試行、タイムアウト処理（cockatiel）
• 構造化ログ：ビルドフィンガープリント機能を備えた Pino ベースのログ記録

セットアップ

1. Google Ads API へのアクセス

必要なもの：

• Google Ads Developer Token（Google Ads API Centerで申請します）
• OAuth 認証情報（Google Cloud Console のクライアント ID とシークレット）
• MCC アカウントの Refresh Token

OAuth 認証情報の取得

1. Google Cloud Consoleにアクセスします
2. プロジェクトを作成するか、既存のプロジェクトを選択します
3. Google Ads API を有効にします
4. Credentials → Create Credentials → OAuth Client ID に進みます
5. Desktop App を選択します
6. JSON をダウンロードします（client_id と client_secret が含まれています）

Refresh Token の取得

独自の OAuth クライアント（上記の手順で取得した client_id / client_secret）を用意し、同梱のヘルパーを実行します。ヘルパーは PKCE（S256）を使用する Google のインストール型アプリ向けループバックフローを実行し、refresh token を出力します。ホームディレクトリから情報を読み取ることはなく、共有 OAuth キーファイルも必要ありません。

export GOOGLE_ADS_CLIENT_ID="YOUR_CLIENT_ID.apps.googleusercontent.com"
export GOOGLE_ADS_CLIENT_SECRET="YOUR_CLIENT_SECRET"
node get-refresh-token.cjs

ブラウザーが開くので、Ads データを所有する Google アカウントでサインインし、承認します。成功すると、ヘルパーは stdout に1行を出力します。

GOOGLE_ADS_REFRESH_TOKEN=1//0a...

この値を環境変数（または以下の config.json）に設定します。要求する OAuth スコープは config.json（oauth.scope）から読み取られ、設定されていない場合は config.example.json が使われるため、ヘルパーと実行中のサーバーは常に同じスコープを要求します。この MCP が要求するのは、必要最小限のスコープのみです。 https://www.googleapis.com/auth/adwords

stdout を共有ログファイルにリダイレクトして実行しないでください。refresh token は仕様上 stdout に出力されます。

注：GOOGLE_ADS_DEVELOPER_TOKEN は OAuth スコープではなく、独立した Google Ads API 認証情報です。個別に設定してください（下記の環境変数を参照）。

2. インストール

npm install mcp-google-ads

または、ソースをクローンしてビルドします。

git clone https://github.com/mharnett/mcp-google-ads.git
cd mcp-google-ads
npm install
npm run build

セキュリティ： .mcp.json ファイルを共有したり、git にコミットしたりしないでください。API 認証情報が含まれている可能性があります。.mcp.json を .gitignore に追加してください。

3. 設定

cp config.example.json config.json

config.json を編集して認証情報を設定します。

{
  "oauth": {
    "scope": "https://www.googleapis.com/auth/adwords"
  },
  "google_ads": {
    "developer_token": "YOUR_DEVELOPER_TOKEN",
    "client_id": "YOUR_CLIENT_ID.apps.googleusercontent.com",
    "client_secret": "YOUR_CLIENT_SECRET",
    "refresh_token": "YOUR_REFRESH_TOKEN",
    "mcc_customer_id": "123-456-7890"
  },
  "clients": {
    "my-client": {
      "customer_id": "111-222-3333",
      "name": "My Client",
      "folder": "/path/to/client/workspace"
    },
    "another-client": {
      "customer_id": "444-555-6666",
      "name": "Another Client",
      "folder": "/path/to/another/workspace"
    }
  },
  "defaults": {
    "create_paused": true,
    "label_prefix": "claude-",
    "require_approval_for_enable": true
  }
}

環境変数

代わりに、環境変数から認証情報を設定することもできます（config.json の設定より優先されます）。

変数	必須	説明
GOOGLE_ADS_DEVELOPER_TOKEN	はい	Google Ads API の developer token
GOOGLE_ADS_CLIENT_ID	はい	OAuth 2.0 クライアント ID
GOOGLE_ADS_CLIENT_SECRET	はい	OAuth 2.0 クライアントシークレット
GOOGLE_ADS_REFRESH_TOKEN	はい	OAuth 2.0 refresh token
GOOGLE_ADS_MCP_WRITE	いいえ	true に設定すると、変更を伴うツール（作成／更新／一時停止／有効化／削除／適用）が公開されます。デフォルト：読み取り専用。
GOOGLE_ADS_MCP_ALWAYS_LOAD	いいえ	常時読み込み対象として指定するツール名をカンマ区切りで指定します。例：google_ads_get_client_context,google_ads_gaql_query。デフォルト：未設定（ツールは指定されません）。

常時読み込みツール

ツール検索の手順を挟んでツールスキーマを遅延読み込みするクライアントでは、検索されたツールのみが読み込まれます。GOOGLE_ADS_MCP_ALWAYS_LOAD にツール名を指定すると、tools/list 内で _meta: {"anthropic/alwaysLoad": true} が付与され、それらのツールが直接提示されます。一致するツールがない名前は無視され、このマーカーによって読み取り専用モードで非表示のツールが公開されることはありません。

デフォルトでは読み取り専用

サーバーは読み取り専用で動作します。変更を加えるツール（作成、更新、一時停止、有効化、削除、リンク、適用を行うもの）は、MCP サーバーの環境で GOOGLE_ADS_MCP_WRITE=true を設定するまで、ツール一覧に表示されません。 このフラグを設定せずに書き込みツールが呼び出された場合、サーバーは環境変数を示す明確なエラーを返します。

これは意図的な仕様です。「Fundraising キャンペーンを有効にして」という何気ないチャットメッセージによって、明示的なオプトインなしに実際の広告費が動くことがあってはなりません。

4. Claude Code に追加する

Claude Code の MCP 設定（~/.claude/settings.json またはプロジェクト設定）に追加します。

{
  "mcpServers": {
    "google-ads": {
      "command": "node",
      "args": ["node_modules/mcp-google-ads/dist/index.js"]
    }
  }
}

ソースからインストールした場合は、次のように追加します。

{
  "mcpServers": {
    "google-ads": {
      "command": "node",
      "args": ["/path/to/mcp-google-ads/dist/index.js"]
    }
  }
}

Claude Code を再起動します。

Claude Desktop： ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）に追加します。

使い方

ワークフロー

1. cd into client folder → auto-detects account context
2. Ask Claude to create campaigns/ads → all created PAUSED
3. Review in Google Ads UI or Editor
4. Tell Claude to enable approved items
5. Claude enables (requires your approval prompt)

利用可能なツール（36）

コンテキストと検出

ツール	説明
google_ads_get_client_context	作業ディレクトリからアカウントを特定する
google_ads_list_campaigns	ステータスと指標を含むすべてのキャンペーンを一覧表示する
google_ads_list_ad_groups	キャンペーン内の広告グループを一覧表示する
google_ads_list_pending_changes	claude- ラベルが付いた一時停止中の項目を表示する
google_ads_list_conversion_actions	コンバージョン アクションを一覧表示する

キャンペーン管理

ツール	説明
google_ads_create_campaign	キャンペーンを作成する（一時停止）。SEARCH および DEMAND_GEN チャネルに対応。より柔軟な入札方式（MANUAL_CPC / MAXIMIZE_CLICKS / MAXIMIZE_CONVERSIONS / TARGET_CPA）、地域と言語のターゲティング、開始日と終了日に対応
google_ads_create_ad_group	広告グループを作成する（一時停止）。type には SEARCH_STANDARD（デフォルト）または DEMAND_GEN_MULTI_ASSET_AD_GROUP を指定できます
google_ads_create_responsive_search_ad	検証付きで RSA を作成する（一時停止）
google_ads_create_image_asset	Demand Gen 広告で使用する画像アセット（PNG/JPG/GIF）をアップロードする（5MB 以下、600×314 以上であることを検証）
google_ads_create_demand_gen_multi_asset_ad	Demand Gen のマルチアセット広告を作成する（一時停止）。API 呼び出し前に文字数と件数の上限を検証し、広告グループが DG でない場合は即座にエラーにする
google_ads_create_keywords	キーワードを作成する（一時停止）
google_ads_validate_ad	RSA を作成せずに検証する
google_ads_enable_items	項目を有効化する（公開する） — 承認が必要
google_ads_pause_items	有効な項目を一時停止する
google_ads_pause_keywords	特定のキーワードを一時停止する
google_ads_update_campaign_budget	キャンペーンの日予算を更新する

トラッキングと URL

ツール	説明
google_ads_get_campaign_tracking	トラッキング テンプレートと URL パラメータを取得する
google_ads_update_campaign_tracking	トラッキング テンプレートを更新する

除外キーワード

ツール	説明
google_ads_create_shared_set	共有の除外キーワード リストを作成する
google_ads_link_shared_set	共有セットをキャンペーンにリンクする
google_ads_unlink_shared_set	共有セットとキャンペーンのリンクを解除する
google_ads_add_shared_negatives	共有の除外キーワード リストにキーワードを追加する
google_ads_remove_shared_negatives	共有リストからキーワードを削除する
google_ads_add_campaign_negatives	キャンペーン単位の除外キーワードを追加する
google_ads_remove_campaign_negatives	キャンペーン単位の除外キーワードを削除する
google_ads_remove_adgroup_negatives	広告グループ単位の除外キーワードを削除する

パフォーマンスとレポート

ツール	説明
google_ads_keyword_performance	品質スコア付きのキーワード指標
google_ads_keyword_performance_by_conversion	コンバージョン アクション別のキーワード指標
google_ads_ad_performance	広告レベルのパフォーマンス指標
google_ads_ad_performance_by_conversion	コンバージョン アクション別の広告指標
google_ads_search_term_report	検索語句クエリレポート
google_ads_search_term_report_by_conversion	コンバージョン アクション別の検索語句
google_ads_search_term_insights	検索語句カテゴリのインサイト
google_ads_search_term_insight_terms	インサイトカテゴリ内の語句
google_ads_keyword_volume	キーワードプランナーによる検索ボリュームの推定値

高度な機能

ツール	説明
google_ads_gaql_query	GAQL クエリを直接実行

コマンドの例

# Check which account you're working with
"What Google Ads account am I connected to?"

# List campaigns
"Show me all campaigns in this account"

# Create a new campaign
"Create a Search campaign for brand terms with $50/day budget"

# Check what's pending review
"What changes are pending my review?"

# After reviewing in Google Ads UI
"Enable the approved ads in the Brand campaign"

# Performance analysis
"Show me keyword performance for the last 30 days, sorted by cost"

# Run custom GAQL
"Run a GAQL query to get all ad groups with CTR below 2%"

例：デマンドジェネレーションキャンペーンを最初から最後まで作成する

# 1. Campaign: $75/day, DEMAND_GEN channel, MAXIMIZE_CONVERSIONS default,
#    targeting Alaska (21134) + Maine (21141) in English
google_ads_create_campaign({
  name: "DG - Spring Promo",
  daily_budget: 75,
  channel_type: "DEMAND_GEN",
  geo_target_ids: ["21134", "21141"],
  start_date: "2026-05-01",
  end_date: "2026-06-30"
})
# → campaign_id: 555123

# 2. Ad group: DEMAND_GEN_MULTI_ASSET_AD_GROUP
google_ads_create_ad_group({
  campaign_id: "555123",
  name: "DG AG 1",
  type: "DEMAND_GEN_MULTI_ASSET_AD_GROUP"
})
# → ad_group_id: 555456

# 3. Image assets (PNG/JPG/GIF, ≥600×314, ≤5MB). Returns {asset_id, ...}
google_ads_create_image_asset({ name: "hero-landscape", file_path: "/abs/path/hero.png" })
# → asset_id: 42001
google_ads_create_image_asset({ name: "hero-square",    file_path: "/abs/path/square.png" })
# → asset_id: 42002
google_ads_create_image_asset({ name: "logo",           file_path: "/abs/path/logo.png" })
# → asset_id: 42003

# 4. Demand Gen multi-asset ad (PAUSED). Validates char + count caps first.
google_ads_create_demand_gen_multi_asset_ad({
  ad_group_id: "555456",
  final_urls: ["https://example.com/spring"],
  business_name: "Example Org",
  call_to_action: "LEARN_MORE",
  marketing_image_asset_ids: ["42001"],          // 1.91:1 landscape, ≥1 required
  square_marketing_image_asset_ids: ["42002"],   // 1:1 optional
  logo_image_asset_ids: ["42003"],               // logo optional
  headlines: ["Spring Sale Now On", "Save 20% Today"],     // max 5, ≤40 chars each
  long_headlines: ["A longer pitch under ninety characters."], // max 5, ≤90 chars
  descriptions: ["Shop the latest looks.", "Free returns."]   // max 5, ≤90 chars each
})
# → resource_name: customers/.../adGroupAds/555456~67890000

4 回の呼び出しがすべて完了すると、キャンペーン、広告グループ、広告がすべて Claude-MM-DD-YY のラベル付きで PAUSED 状態のままアカウントに作成されます。Google Ads UI で確認してから、google_ads_enable_items で有効にしてください。

安全機能

1. すべて PAUSED 状態で開始 — 明示的に有効にするまで、何も配信されません
2. ラベルによる追跡 — Claude が作成したすべてのアイテムに claude-pending ラベルが付与されます
3. 検証 — 広告は作成前に検証されます（見出しや説明文の長さなど）
4. 承認プロンプト — enable_items ツールを使うには、Claude Code で明示的な承認が必要です
5. クライアントの分離 — 作業ディレクトリによって対象アカウントが決まるため、クライアント間の取り違えを防げます

クライアントの追加

config.json を編集してクライアントを追加します。各クライアントを作業ディレクトリに割り当ててください。

{
  "clients": {
    "client-slug": {
      "customer_id": "123-456-7890",
      "name": "Client Name",
      "folder": "/path/to/client/workspace"
    }
  }
}

サーバーを再起動する必要はありません。設定はリクエストごとに読み込まれます。

トラブルシューティング

「作業ディレクトリに対応するクライアントが見つかりません」

• clients のエントリに一致するフォルダーにいることを確認してください
• config.json のフォルダーパスが完全に一致していることを確認してください

「デベロッパートークンが承認されていません」

• 新しいデベロッパートークンは Google による承認が必要です
• 承認を待つ間はテストアカウントを使用してください

「認証に失敗しました」

• 更新トークンの有効期限が切れている可能性があります。再生成してください
• client_id と client_secret が正しいことを確認してください

ライセンス

MIT — 詳細は LICENSE を参照してください。