google-ads-mcp
Operates Google Ads accounts via the Google Ads API: retrieve performance reports (account, campaign, ad group, daily), list campaigns/ad groups/ads and their status and budgets, run arbitrary GAQL queries, and access Keyword Planner data (monthly search volume, competition, bid ranges). It also supports campaign creation and management, including creating budgets, search and Performance Max campaigns, ad groups, keywords and negative keywords, responsive search ads, and P-MAX asset groups (with images from local paths or URLs), plus pausing/enabling delivery, changing daily budgets, removing campaigns/ad groups/ads, and sending raw mutate requests.
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
セットアップ
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
Tools mostly target distinct resources and actions (create_budget vs update_budget, update_status vs remove, report vs search vs list_objects). The main overlap is among read tools—google_ads_report, google_ads_list_objects, and google_ads_search can all return overlapping data—but the descriptions explicitly delineate typed vs arbitrary GAQL queries and metrics vs entity listings. google_ads_mutate overlaps with all write tools, though it is clearly framed as a last-resort fallback.
Almost all tools share a snake_case google_ads_ prefix and verb-noun form (list_accessible_customers, create_campaign, update_status, etc.). Minor deviations are noun-only names like google_ads_account_info, google_ads_report, and google_ads_keywords, but the overall pattern remains readable and predictable.
16 tools cover a broad Google Ads surface (read, create, update, delete, plus a generic mutate), so each tool earns a place. It sits just above the ideal 3-15 range and could arguably be trimmed, but the count is reasonable for the domain's complexity.
The set provides solid CRUD coverage across budgets, campaigns, ad groups, ads, keywords, plus reporting and keyword research. Gaps exist (no typed update for renaming campaigns/ad groups or bidding details, limited ad-type creation), but google_ads_mutate and google_ads_search act as escape hatches for uncovered operations.
Related MCP Connectors
Google Ads MCP: reports, search terms, negatives, budgets, campaigns. Approval on every write.
Google Ads MCP server — manage campaigns, keywords, and metrics.
Hosted Google Ads MCP with OAuth, bounded reads, and prepare/confirm writes.
Google Ads MCP with 20,000+ account peer context and staged approve-then-execute writes.
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.-
- AlicenseAqualityBmaintenanceEnables MCP clients to report on and manage Google Ads accounts, including GAQL queries, performance metrics, search terms, budgets, and campaign management.216 npmMIT
- 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
- AlicenseAqualityCmaintenanceEnables MCP clients such as Claude to read Google Ads performance reports, run keyword planner queries, and create or manage search and Performance Max campaigns, ad groups, keywords, ads, budgets, and delivery status. Write operations default to paused and can be disabled entirely for read-only analytics use.16MIT