google-ads-mcp

google-ads-mcp-unofficial

AI エージェントが Google Ads アカウントを読み取り、分析し、（制限付きで）操作できる非公式の Model Context Protocol サーバーです。スタックを離れることなく、キーワードの一時停止、入札単価の設定、予算の調整を行えます。

非公式です。Google とは提携していません。 Google Ads REST API と直接通信する、ローカル優先の MCP サーバーです。Google Ads API が許可する範囲を超えて、金融アカウントを自動で変更する機能は含まれていません。GOOGLE_ADS_ALLOW_MUTATIONS を有効にする前に、変更案を必ず確認してください。

---

HTTP（v2 ステートレス）

デフォルトは stdio です。オプションで Streamable HTTP を利用できます。セッション ID は不要で、JSON レスポンスを返し、ループバックのみで動作します。

npx -y google-ads-mcp-unofficial --http
# GET  http://127.0.0.1:3000/health
# POST http://127.0.0.1:3000/mcp   (sessionless)

環境変数：GOOGLE_ADS_MCP_HOST、GOOGLE_ADS_MCP_PORT、GOOGLE_ADS_MCP_TRANSPORT=http。

クイックスタート（30 秒）

npx -y google-ads-mcp-unofficial setup

セットアップウィザードは、開発者トークンと OAuth クライアントを収集して ~/.google-ads-mcp/config.json に書き込み（chmod 600）、ローカルコールバック http://127.0.0.1:3000/callback を使って OAuth の手順を進めます。

確認：

npx -y google-ads-mcp-unofficial doctor

続いて、エージェント（Claude Desktop、Cursor、Hermes、OpenClaw、Codex。以下の例を参照）に追加します。

---

機能

6 カテゴリーにわたる 22 個のツールを提供します。

カテゴリー	数	例
メタ／診断	5	google_ads_connection_status、google_ads_capabilities、google_ads_agent_manifest、google_ads_data_inventory、google_ads_privacy_audit
共有 Delx プロファイル	3	google_ads_profile_get、google_ads_profile_update、google_ads_onboarding
認証	3	google_ads_get_auth_url、google_ads_exchange_code、google_ads_revoke_access
読み取り（常に安全）	8	google_ads_list_accounts、google_ads_list_campaigns、google_ads_get_campaign、google_ads_list_ad_groups、google_ads_list_keywords、google_ads_get_account_performance、google_ads_get_campaign_performance、google_ads_get_keyword_performance
ワークフロー	2	google_ads_daily_report、google_ads_find_waste
変更（制限付き）	6	google_ads_pause_keyword、google_ads_resume_keyword、google_ads_set_keyword_bid_micros、google_ads_set_campaign_budget_micros、google_ads_pause_campaign、google_ads_resume_campaign

ツールの詳細なリファレンスは AGENTS.md を参照してください。

---

セットアップウィザード

npx -y google-ads-mcp-unofficial setup [--allow-mutations] [--client hermes|claude|cursor|...]

機能：

1. 開発者トークン、OAuth クライアント ID／シークレット、任意の login_customer_id（MCC）、リダイレクト URI、プライバシーモードの入力を求めます。
2. ~/.google-ads-mcp/config.json を chmod 600 で書き込みます。
3. MCP クライアント設定を書き込みます（例：macOS では claude_desktop_config.json にマージします。--client hermes の場合は Hermes のブロックとスキルファイルを書き込みます）。
4. （--no-auth を指定しない限り）Google の同意画面を開き、127.0.0.1:3000 でリッスンして OAuth の手順を進めます。

変更はデフォルトで無効です。 --allow-mutations を指定すると書き込みツールが有効になります。有効にする前にユーザーに確認してください。エージェントがキャンペーン、入札単価、予算を変更し、キーワードを一時停止／再開できるようになります。

---

認証モデル

この MCP には、2 つの認証情報が必要です。

1. Google Ads Developer Token — MCC（マネージャー）アカウントで https://ads.google.com/aw/apicenter から取得します。新しいトークンは「テストアカウントアクセス」モードで発行され、本番トラフィックで使用するには承認が必要です。
2. Google OAuth 2.0 クライアント — Google Cloud Console で作成した「デスクトップ」または「ウェブ」クライアントです。使用する OAuth スコープは https://www.googleapis.com/auth/adwords のみです。

⚠️ リフレッシュトークンに関する注意点： Google は、初回の同意時、または https://myaccount.google.com/permissions で以前の許可を取り消した後にのみ、refresh_token を返します。auth フローでは、Google がトークンを返す可能性を高めるために prompt=consent を使用します。ただし、コード交換のレスポンスに refresh_token が含まれていない場合、ツールから許可を取り消して再試行するよう案内されます。

変数	用途	保存場所	シークレット？
GOOGLE_ADS_DEVELOPER_TOKEN	承認済みのデベロッパートークン	~/.google-ads-mcp/config.json または環境変数	はい
GOOGLE_ADS_CLIENT_ID	OAuth クライアント ID	ローカルまたは環境変数	いいえ
GOOGLE_ADS_CLIENT_SECRET	OAuth クライアントシークレット	ローカルまたは環境変数	はい
GOOGLE_ADS_LOGIN_CUSTOMER_ID	MCC ID（ハイフンなし）	ローカルまたは環境変数	いいえ
GOOGLE_ADS_REDIRECT_URI	OAuth コールバック	ローカルまたは環境変数（デフォルトは http://127.0.0.1:3000/callback）	いいえ
GOOGLE_ADS_PRIVACY_MODE	summary | structured | raw	ローカルまたは環境変数（デフォルトは structured）	いいえ
GOOGLE_ADS_ALLOW_MUTATIONS	書き込みツールを有効化	ローカルまたは環境変数（デフォルトは false）	いいえ
GOOGLE_ADS_TOKEN_PATH	トークンの保存場所を上書き	ローカルまたは環境変数（デフォルトは ~/.google-ads-mcp/tokens.json）	いいえ
GOOGLE_ADS_CACHE	SQLite キャッシュを有効化	ローカルまたは環境変数（デフォルトはオフ）	いいえ
GOOGLE_ADS_CACHE_PATH	キャッシュのパスを上書き	ローカルまたは環境変数	いいえ
GOOGLE_ADS_NO_RETRY	リトライミドルウェアを無効化	環境変数（デフォルトはオフ）	いいえ

---

プライバシーモード

モード	取得できる情報	顧客 ID
summary	ID、名前、ステータスのフィールドのみ	一部をマスキング（123-***-7890）
structured（デフォルト）	指標を含む、フラットで正規化された行	一部をマスキング
raw	Google Ads REST の上流からの完全なペイロード	完全表示

呼び出しごとに privacy_mode を指定すると、レスポンスごとにデフォルトを上書きできます。

マスキング一覧：

フィールド	summary	structured	raw
developer_token	該当なし	該当なし	該当なし（返されません）
access_token、refresh_token、client_secret	すべてのエラーで [REDACTED]	[REDACTED]	[REDACTED]
エラーメッセージ内のメールアドレス	[REDACTED]	[REDACTED]	[REDACTED]
customer_id	123-***-7890	123-***-7890	完全表示
指標（クリック数、費用など）	省略	含む	含む

---

⚠️ 変更操作の制御 — 必ずお読みください

デフォルトでは、変更操作は無効です。 6 つのツールが制限されています。

• google_ads_pause_keyword / google_ads_resume_keyword
• google_ads_set_keyword_bid_micros
• google_ads_set_campaign_budget_micros
• google_ads_pause_campaign / google_ads_resume_campaign

GOOGLE_ADS_ALLOW_MUTATIONS を有効にせずにエージェントがこれらのいずれかを呼び出すと、次の内容が返されます。

Error: Write tools are disabled. To enable: re-run `google-ads-mcp-server setup --allow-mutations`
or enable GOOGLE_ADS_ALLOW_MUTATIONS. ASK THE USER BEFORE TURNING THIS ON — it lets agents
change campaigns, bids, budgets, and pause/resume keywords.

環境変数を有効にした場合でも、すべての変更操作で呼び出しごとの引数に explicit_user_intent: true が必要です。また、すべての変更操作はリソース名とともに stderr に記録されます。

[google-ads-mcp] MUTATION pause_keyword {"resource_name":"customers/1234567890/adGroupCriteria/999~111222333"}

脅威モデルについては SECURITY.md をお読みください。

---

エージェントクライアントの設定例

Claude Desktop

macOS の場合、~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "google-ads": {
      "command": "npx",
      "args": ["-y", "google-ads-mcp-unofficial"]
    }
  }
}

その後、Claude Desktop を再起動します。

Cursor / Windsurf

~/.cursor/mcp.json（または IDE に相当するファイル）：

{
  "mcpServers": {
    "google-ads": {
      "command": "npx",
      "args": ["-y", "[email protected]"]
    }
  }
}

Hermes

# ~/.hermes/config.yaml
mcp_servers:
  google-ads:
    command: npx
    args:
      - -y
      - [email protected]
    timeout: 120
    connect_timeout: 60
    sampling:
      enabled: false

その後、/reload-mcp を実行します（通常のデータアクセスではゲートウェイを再起動しないでください）。

OpenClaw

~/.openclaw/mcp.servers.json：

{
  "google-ads": {
    "command": "npx",
    "args": ["-y", "[email protected]"]
  }
}

Codex / TOML クライアント

同等の TOML ブロックについては examples/codex.toml をご覧ください。

---

ワークフローの例

1. 日次パフォーマンス概要

// Agent asks: "How did my Google Ads do yesterday?"
{
  "name": "google_ads_daily_report",
  "arguments": {
    "customer_id": "1234567890",
    "cpc_alert_threshold": 0.15
  }
}

前日、過去 7 日間、過去 30 日間の集計を含む Markdown を返します。前日の CPC が 0.15 を超える場合、出力に ALERT バナーが表示されます。

2. 無駄を特定する（読み取り専用）

{
  "name": "google_ads_find_waste",
  "arguments": {
    "customer_id": "1234567890",
    "date_range": "LAST_30_DAYS",
    "min_clicks": 5,
    "min_cost_micros": 200000,
    "zero_conversions_only": true
  }
}

「費用が 0.20 ドル以上、クリック数が 5 回以上、コンバージョン数が 0」の条件に一致するキーワードを、順位付きで返します。ただし、一時停止はしません。

3. 単一のキーワードを一時停止する（変更、確認必須）

ユーザーの確認後：

{
  "name": "google_ads_pause_keyword",
  "arguments": {
    "customer_id": "1234567890",
    "ad_group_id": "999",
    "criterion_id": "111222333",
    "explicit_user_intent": true
  }
}

---

トラブルシューティング

症状	対処方法
Missing required Google Ads environment variables	setup を実行するか、エラーに記載されている環境変数を設定してください。
Google did not return a refresh_token	https://myaccount.google.com/permissions でアクセスを取り消してから、auth を再実行してください。
読み取り時に PERMISSION_DENIED が発生する	GOOGLE_ADS_LOGIN_CUSTOMER_ID が、対象の顧客を所有する MCC と一致していることを確認してください（ハイフンなし）。
Write tools are disabled	想定される動作です。GOOGLE_ADS_ALLOW_MUTATIONS を有効にする前に、ユーザーに確認してください。
設定を編集した後、Hermes ツールが見つからない	/reload-mcp または hermes mcp test google-ads を実行してください。ゲートウェイは再起動しないでください。
トークンファイルのアクセス権が安全でないという警告が表示される	chmod 600 ~/.google-ads-mcp/tokens.json

---

サポート

• GitHub の課題：https://github.com/davidmosiah/google-ads-mcp-unofficial/issues
• メール：[email protected]
• X：@delx369

---

免責事項

非公式の連携機能です。Google とは提携していません。 この MCP には、Google Ads REST API で許可されている範囲を超える、財務アカウントへの自動変更機能は含まれていません。GOOGLE_ADS_ALLOW_MUTATIONS を有効にする前に、提案された変更を必ず確認してください。Google Ads アカウントへの自動変更による予算超過、キャンペーンの一時停止、その他あらゆる結果について、作者は責任を負いません。

MIT ライセンスです。

スキルまたは MCP

同じパッケージに、2 つの利用方法があります。MCP は stdio/HTTP でツールを登録します。クライアントが MCP に対応していない場合、スキルを使って CLI 経由で同じツールを実行できます。

npx -y google-ads-mcp-unofficial call google_ads_connection_status --json '{}'

skill/SKILL.md をエージェントのスキルディレクトリにコピーしてください。