google-ads-mcp
Allows interaction with the Google Ads API to retrieve account information, performance reports, keyword planner data, and campaign objects, and to create and manage budgets, campaigns, ad groups, keywords, responsive search ads, P-MAX asset groups, delivery status, and budget changes.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@google-ads-mcp show me last month's campaign performance"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
google-ads-mcp
Google 広告(Google Ads API)を Claude などの MCP クライアントから操作するための MCP サーバーです。
npx で起動します。実績の取得、キーワードプランナー、検索広告と P-MAX の入稿、配信の開始・停止、予算の変更ができます。
必要なもの
取得場所 | |
開発者トークン | Google 広告の管理者(MCC)アカウントの API センター。本番アカウントを触るには「基本(Basic)アクセス」以上が必要です |
OAuth クライアント ID / シークレット | Google Cloud コンソールで Google Ads API を有効にし、種類「デスクトップ アプリ」の OAuth クライアントを作成 |
refresh token | 下記の |
顧客 ID | Google 広告の管理画面右上の 10 桁の番号(広告を配信しているアカウントのもの。MCC の ID ではない) |
Node.js 18.17 以上が必要です。サービスアカウントでは動きません(Google 広告はアカウントにユーザーとして招待された Google アカウントが必要です)。
Related MCP server: Google Ads MCP Server
セットアップ
1. refresh token を取得する
GOOGLE_ADS_CLIENT_ID=xxx GOOGLE_ADS_CLIENT_SECRET=yyy npx -y github:trip-clear/google-ad-mcp authブラウザが開くので、Google 広告を操作できる Google アカウントで許可します。ターミナルに GOOGLE_ADS_REFRESH_TOKEN=... が表示されます。
2. MCP クライアントに登録する
Claude Code:
claude mcp add google-ads \
-e GOOGLE_ADS_DEVELOPER_TOKEN=... \
-e GOOGLE_ADS_CLIENT_ID=... \
-e GOOGLE_ADS_CLIENT_SECRET=... \
-e GOOGLE_ADS_REFRESH_TOKEN=... \
-e GOOGLE_ADS_CUSTOMER_ID=123-456-7890 \
-- npx -y github:trip-clear/google-ad-mcpClaude Desktop など(mcpServers の設定):
{
"mcpServers": {
"google-ads": {
"command": "npx",
"args": ["-y", "github:trip-clear/google-ad-mcp"],
"env": {
"GOOGLE_ADS_DEVELOPER_TOKEN": "...",
"GOOGLE_ADS_CLIENT_ID": "...",
"GOOGLE_ADS_CLIENT_SECRET": "...",
"GOOGLE_ADS_REFRESH_TOKEN": "...",
"GOOGLE_ADS_CUSTOMER_ID": "123-456-7890"
}
}
}
}github:trip-clear/google-ad-mcp は、この GitHub リポジトリから直接取得して起動する指定です(npm には公開していません)。リポジトリを clone してある場合は、そのパスを渡しても同じように動きます(npx -y /path/to/google-ad-mcp)。
3. 疎通を確かめる
クライアントから google_ads_account_info を呼び、アカウント名と通貨が返れば接続できています。
環境変数
変数 | 必須 | 内容 |
| ○ | 開発者トークン |
| ○ | OAuth クライアント ID |
| ○ | OAuth クライアントシークレット |
| ○ | refresh token |
| 既定の顧客 ID。各ツールの | |
| MCC 経由で子アカウントを操作するときの MCC の ID | |
| API バージョン。既定 | |
|
|
ツール
読み取り:
ツール | 内容 |
| 連携したアカウントが操作できる顧客 ID の一覧 |
| アカウント名・通貨・タイムゾーン・MCC かどうか |
| 期間の実績(アカウント / キャンペーン / 広告グループ別、日次も可) |
| キャンペーン / 広告グループ / 広告の一覧と状態・予算 |
| 任意の GAQL を実行(検索語句、キーワード別実績など) |
| キーワードプランナー(月間検索ボリューム・競合性・入札レンジ) |
書き込み(GOOGLE_ADS_READ_ONLY=true では非公開):
ツール | 内容 |
| キャンペーン予算を作成 |
| キャンペーンを作成(検索 / P-MAX) |
| 広告グループを作成 |
| キーワード / 除外キーワードを追加 |
| レスポンシブ検索広告を作成 |
| P-MAX のアセットグループを作成(画像はローカルパスか URL) |
| 配信の開始(ENABLED)・停止(PAUSED) |
| 日予算を変更 |
| キャンペーン / 広告グループ / 広告を削除(元に戻せません) |
| 上記で足りない操作を |
入稿の順番は決まっています。
google_ads_create_budget
└─ google_ads_create_campaign
├─ 検索: google_ads_create_ad_group → google_ads_add_keywords / google_ads_create_responsive_search_ad
└─ P-MAX: google_ads_create_asset_group書き込みの安全策
Google Ads API の adwords スコープは読み取りと書き込みが分かれていません。このサーバーは次の形で事故を防ぎます。
作成するものはすべて既定で
PAUSEDです。配信の開始はgoogle_ads_update_statusを別に呼ぶ必要があります。検索キャンペーンは、明示しない限り検索パートナーとディスプレイに配信しません。
見出し・説明文の本数と文字数(全角は 2 文字と数えます)は、Google に送る前に検算します。
google_ads_create_asset_groupとgoogle_ads_mutateはvalidate_only=trueで、何も変更せずに Google 側の検算だけ行えます。分析だけに使うなら
GOOGLE_ADS_READ_ONLY=trueを設定してください。
書き込みツールを実際に実行するかどうかの承認は、MCP クライアント側の許可設定に任せています。書き込みツールを自動許可にしないことをおすすめします。
数字の読み方
costMicros/amountMicrosは、通貨に関係なく 100 万で割ると通貨 1 単位(円なら円)になります。impressions/clicks/costMicrosは文字列で返ります。conversionsは小数になりえます。metrics.ctrは 0〜1 の比率です(% ではありません)。metrics.conversionsの定義は、Google 広告の管理画面で「コンバージョン列に含める」としたアクションの合計です。キーワードプランナーの
avg_monthly_searchesがnullのときは 0 ではなく「データ無し」です。competitionは広告枠の競合度であり、SEO の難易度ではありません。
トラブルシューティング
症状 | 原因と対処 |
| 開発者トークンが Test のままです。基本アクセスを申請するか、テストアカウントで検証します |
| 連携した Google アカウントがその顧客 ID のユーザーではありません。MCC 配下なら |
| 顧客 ID が違います。 |
| refresh token が失効しています。 |
実績が常に空 | MCC の ID を指定しています。配信している子アカウントの ID を指定します |
広告の停止・削除で ID エラー | 広告の ID は |
開発
npm install
npm test # Google への通信はモック
node bin/cli.js # stdio で起動ライセンス
MIT
Available Tools
16 toolsgoogle_ads_account_infoGoogle 広告アカウントの情報を取得ARead-only
顧客アカウントの名前・通貨・タイムゾーン・MCC かどうかを返す。**読み取り専用。**疎通確認と、予算を触る前の通貨確認に使う。
Inputs: customer_id.
google_ads_add_keywordsGoogle 広告にキーワードを追加A
広告グループにキーワードを追加する。negative=true で除外キーワードになる(あとから通常のキーワードには変えられないので、間違えたら消して作り直すことになる)。
Inputs: keywords (required), ad_group_resource_name (required), negative, match_type, +1 more.
google_ads_create_ad_groupGoogle 広告の広告グループを作成A
検索キャンペーンに広告グループを作る。日予算は持てない——Google 広告の予算はキャンペーンにしかない。既定は PAUSED。
Inputs: name (required), campaign_resource_name (required), status, cpc_bid, +1 more.
google_ads_create_asset_groupP-MAX のアセットグループを作成A
P-MAX のアセットグループを作る(P-MAX に広告グループも広告も無い)。テキスト・画像・アセットグループ・リンクを1 回の mutate で作る(Google の要求)。画像はローカルのファイルパスか http(s) の URLで指定する(1 枚 5120 KB まで)。必須: 見出し 3〜15(30字)/ 長い見出し 1〜5(90字)/ 説明 2〜5(90字)/ ビジネス名 1(25字)/ 横長画像 1〜20(1.91:1)/ 正方形画像 1〜20(1:1)/ ロゴ 1〜5(1:1)。字数は全角を 2 と数えるので、日本語では上限が半分。1 つでも足りないと Google がリクエスト全体を拒否するので、先に validate_only=true で検算するとよい。既定は PAUSED。
Inputs: name (required), logos (required), headlines (required), final_urls (required), +11 more.
google_ads_create_budgetGoogle 広告のキャンペーン予算を作成A
キャンペーン予算を作る。Google 広告では予算がキャンペーンとは別のリソースなので、キャンペーンより先にこれを作る。金額は通貨 1 単位(円なら円)で渡す——マイクロ換算はサーバー側で行う。
Inputs: name (required), daily_amount (required), customer_id.
google_ads_create_campaignGoogle 広告のキャンペーンを作成A
キャンペーンを作る(検索 / P-MAX)。既定は PAUSED(作成と配信開始は別の操作にする)。budget_resource_name は google_ads_create_budget の戻り値。検索では検索パートナー・ディスプレイへの配信を既定で切ってある。P-MAX に手動入札は無く、広告グループも広告も無い(代わりに google_ads_create_asset_group でアセットグループを作る。無いと配信できない)。
Inputs: name (required), budget_resource_name (required), status, channel, +7 more.
google_ads_create_responsive_search_adGoogle 広告の検索広告を作成A
レスポンシブ検索広告を作る。見出しは 3〜15 本(各 30 文字以内)、説明文は 2〜4 本(各 90 文字以内)。字数は全角を 2 と数えるので、日本語では上限が半分(見出し 15 / 説明文 45)。既定は PAUSED。
Inputs: headlines (required), final_urls (required), descriptions (required), ad_group_resource_name (required), +4 more.
google_ads_keywordsキーワードの検索ボリュームと入札単価を調査ARead-only
Keyword Planner でキーワードの月間平均検索ボリューム・競合性・入札レンジを取る。**読み取り専用。**入札額はマイクロ単位(1,000,000 = 通貨 1 単位)。関連キーワードの候補も返る。
Inputs: keywords (required), customer_id, language_id, geo_target_ids.
google_ads_list_accessible_customers操作できる Google 広告アカウントの一覧ARead-only
連携した Google アカウントが直接アクセスできる顧客 ID を一覧する。**読み取り専用。**名前は返らないので、google_ads_account_info で確かめる。
Inputs: no named parameters.
google_ads_list_objectsGoogle 広告のキャンペーン一覧を取得ARead-only
キャンペーン / 広告グループ / 広告を一覧する。**読み取り専用。**配信状態は ENABLED / PAUSED(ACTIVE ではない)。日予算はキャンペーンにしか無い。REMOVED は除外する。
Inputs: kind, row_limit, customer_id.
google_ads_mutateGoogle 広告へ操作を送信ADestructive
型付きツールで足りない書き込みを通す最後の手段(googleAds:mutate)。validate_only=true にすると Google 側で検算だけ行い何も変更しないので、複雑な操作は先にこれで通してから本番に送ること。
Inputs: mutate_operations (required), customer_id, validate_only.
google_ads_removeGoogle 広告のキャンペーン・広告を削除ADestructive
キャンペーン / 広告グループ / 広告を削除する。**元に戻せない。**止めたいだけなら google_ads_update_status で PAUSED にする。広告(kind=ad)の ID は「広告グループID~広告ID」の複合キー。
Inputs: object_id (required), kind, customer_id.
google_ads_reportGoogle 広告の実績を取得ARead-only
Google 広告の実績(費用・表示・クリック・CV・CV 値)を取得する。読み取り専用。costMicros は 100 万で割ると通貨 1 単位(通貨に依らず一律)。conversions は小数になりうる。int64 の項目は proto3 JSON の規則で文字列として返る。CTR / CPC は返り値から自分で計算すること。
Inputs: end_date (required), start_date (required), level, by_date, +1 more.
google_ads_searchGAQL で Google 広告を検索ARead-only
任意の GAQL(Google Ads Query Language)を googleAds:searchStream で実行する。**読み取り専用。**型付きツールで取れない項目(検索語句・キーワード別実績・アセット・地域別など)に使う。フィールド名は snake_case(例: SELECT campaign.name, metrics.clicks FROM campaign WHERE segments.date DURING LAST_30_DAYS)。返り値のキーは camelCase、int64 は文字列。
Inputs: query (required), row_limit, customer_id.
google_ads_update_budgetGoogle 広告の日予算を変更A
キャンペーン予算の日予算を変える。宛先はキャンペーンではなく予算リソース(google_ads_list_objects が返す campaignBudget.id)。金額は通貨 1 単位(円なら円)。
Inputs: budget_id (required), daily_amount (required), customer_id.
google_ads_update_statusGoogle 広告の配信状態を変更A
キャンペーン / 広告グループ / 広告の配信を開始(ENABLED)・停止(PAUSED)する。配信中は ENABLED(ACTIVE ではない)。ENABLED にすると課金が始まりうる。広告(kind=ad)の ID は「広告グループID~広告ID」の複合キー。削除は google_ads_remove。
Inputs: status (required), object_id (required), kind, customer_id.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 16 tools
Each tool targets a distinct resource and action (budget, campaign, ad group, keywords, asset group, status, report). Minor overlap exists between google_ads_search, google_ads_report, and google_ads_list_objects (all reads), and google_ads_mutate overlaps with the typed create/update tools, but the descriptions clearly position search and mutate as escape hatches for what typed tools can't do.
All tools share a consistent google_ads_ prefix and mostly follow a verb_noun pattern (create_budget, create_campaign, update_status, list_objects, add_keywords). A few are noun-only deviations (account_info, report, keywords, search, mutate) but the overall convention is predictable and readable.
16 tools is at the upper edge but justified given Google Ads' complexity across budgets, campaigns, ad groups, ads, keywords, asset groups, reporting, and mutations. Each tool maps to a distinct operation, with search and mutate serving as deliberate catch-alls rather than filler.
The surface covers the core lifecycle: create budget/campaign/ad group/keywords/RSA/asset group, update status and budget, remove, plus reporting and arbitrary GAQL reads. Gaps exist (no typed update for ad/ad group content beyond status, no conversion-tracking management), but the google_ads_mutate and google_ads_search escape hatches let agents work around these.
Maintenance
Related MCP Connectors
Google Ads MCP: reports, search terms, negatives, budgets, campaigns. Approval on every write.
Manage Google Ads from ChatGPT, Claude or any MCP client. Sign in with OAuth or use an API key.
Google Ads MCP server: run Search, Display, Demand Gen and PMax campaigns from AI.
Hosted Google Ads MCP for Claude and ChatGPT. Preview every write. No developer token.
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceEnables management of Google Ads accounts via MCP, providing read and write tools for campaigns, ad groups, keywords, assets, and more, with support for reporting and mutations.-
- AlicenseBqualityCmaintenanceEnables Claude and other MCP-capable assistants to monitor and manage Google Ads accounts by pulling performance reports, running GAQL queries, adjusting budgets, pausing or enabling campaigns, adding keywords and negative keywords, and creating campaigns and ads, with preview and read-only safety controls.31Apache 2.0
- AlicenseAqualityCmaintenanceEnables MCP clients to retrieve Google Ads performance data, run GAQL queries and keyword planner research, and create or manage search and P-MAX campaigns, budgets, keywords, and ad status. Includes safety defaults such as paused creation and read-only mode.16MIT
- AlicenseNot gradedqualityCmaintenanceEnables MCP clients such as Claude to manage Google Ads accounts through the Google Ads API, including performance reporting, keyword planning, search and P-MAX campaign creation, status changes, and budget updates.MIT