Google 広告 MCP サーバー: デベロッパー向け統合ガイド

Model Context Protocol（MCP）は、大規模言語モデル（LLM）が外部のデータやアプリケーションと安全にやり取りできるようにするオープン標準です。Google 広告 MCP サーバーは、Google Ads API への標準化されたブリッジを提供します。これにより、AI エージェントは自然言語を使用してキャンペーン データを分析、取得できます。

コミュニティ リソースとサポート

技術的概要

この MCP サーバーを実装すると、Google Ads API の認証、リソースの取得、データの解析用にカスタムの「グルーコード」を記述する必要がなくなります。サーバーは、LLM が自律的に検出して呼び出すことができる特定のツールを公開します。

主な仕様

  • プロトコル: MCP（Model Context Protocol）
  • モード: 読み取り専用（現在のリリース）
  • 言語: Python
  • トランスポート: 標準入出力（stdio）またはストリーミング可能な HTTP（streamable-http / Cloud Run）
  • 認証: OAuth 2.0 またはサービス アカウント

インタラクション ループの仕組み

  1. リクエスト: ユーザーが「今週のキャンペーンのパフォーマンスはどうですか？」などのクエリを送信します。
  2. 検出: LLM は、使用可能なツールを検査し、google-ads-mcp 検索機能を特定します。
  3. 実行: MCP サーバーは、基盤となる Python ロジックを実行して Google Ads API にクエリを実行します。
  4. コンテキスト インジェクション: 構造化された結果が LLM のコンテキスト ウィンドウに返されます。
  5. 回答: LLM はデータを合成して、対人可読な回答を生成します。

始める

Google 広告 MCP サーバーを構成して使用する手順は次のとおりです。

前提条件

構成する前に、Google Cloud コンソールから次の認証情報を取得していることを確認してください。

構成

サーバーを MCP 互換ホストに統合するには、ホストの MCP 構成ファイル（settings.json など）に次のエントリを追加し、GOOGLE_APPLICATION_CREDENTIALS が ADC JSON ファイルを指すようにします（または gcloud auth application-default login でデフォルトの ADC を構成します）。マネージャー アカウントを介してアカウントにアクセスする場合は、GOOGLE_ADS_LOGIN_CUSTOMER_ID を設定することもできます。この構成の正確な場所とファイル名については、ホストのドキュメントをご覧ください。

{
  "mcpServers": {
    "google-ads-mcp": {
      "command": "pipx",
      "args": [
        "run",
        "--spec",
        "git+https://github.com/googleads/google-ads-mcp.git",
        "google-ads-mcp"
      ],
      "env": {
        "GOOGLE_PROJECT_ID": "YOUR_PROJECT_ID",
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/credentials.json"
      }
    }
  }
}

省略可: エージェントにスキルと Developer Assistant を装備する

Google 広告 MCP サーバーを使用すると、AI クライアントにライブ アカウント データへの読み取り専用アクセス権を付与できます。エージェントが有効な Google Ads Query Language（GAQL）クエリを作成し、アカウントのパフォーマンスの変化を診断し、クライアント ライブラリ コードを生成できるようにするには、MCP サーバーを次のコンパニオン ツールと組み合わせます。

  • Google Ads API エージェント スキル: Google Ads API 固有の手順とワークフロー（google-ads-api-mcp-setup、google-ads-api-account-diagnostics、google-ads-api-quickstart など）のポータブル モジュール。トークンのオーバーヘッドを抑えながら Google 広告 MCP サーバーを効果的に使用する方法をエージェントに指示します。1 つのコマンドでインストールします（Node.js が必要）。または、Google Ads API エージェント スキルガイドで、Antigravity、Claude Code、Codex、Cursor のオプションをご覧ください。

    npx skills add google/skills/skills/ads

  • Google Ads API Developer Assistant: Google Antigravity と Claude Code のモジュラー プラグイン。ローカルの Protobuf スキーマ検査、プログラムによる GAQL 検証、クライアント ライブラリ コード生成（ミューテーション スクリプトを含む）、オフライン コンバージョンのトラブルシューティングを提供します。仕組みについては、Google Ads API Developer Assistant とはをご覧ください。または、インストール ガイドに沿って操作してください。

Google Cloud へのデプロイ

この MCP サーバーは、ローカルでホストする代わりに、Google Cloud Run やその他のクラウドベースのインフラストラクチャでホストできます。これは、異なるエージェント間でサーバーを共有する場合や、ウェブサービスとして実行する場合に便利です。

前提条件

  1. Google Cloud プロジェクト

  2. gcloud コマンドライン ツールがインストールされ、認証され、アクティブなプロジェクトが構成されていること。

    gcloud config set project YOUR_PROJECT_ID

Docker イメージをビルドして push する

Cloud Build を使用すると、Docker をローカルにインストールしなくても、イメージをビルドして Artifact Registry に push できます。

  1. Artifact Registry にリポジトリを作成します。

    gcloud artifacts repositories create mcp-servers \
  --repository-format=docker --location=us-central1

  2. プロジェクト ディレクトリに移動します。

    cd <full path>/google-ads-mcp

  3. イメージをビルドして送信します。

    gcloud builds submit \
  --tag us-central1-docker.pkg.dev/YOUR_PROJECT_ID/mcp-servers/google-ads-mcp:latest .

    この手順は、デプロイされたサーバーを最新バージョンに更新するたびに実行する必要があります。

Google Cloud Run にデプロイ

必要な環境変数を設定します。

  • GOOGLE_PROJECT_ID: 適切な API アクセスレベルを持つ Google Cloud プロジェクト ID。
  • GOOGLE_ADS_MCP_OAUTH_CLIENT_ID: アプリケーション レベルの OAuth 認証用の OAuth 2.0 クライアント ID（Google Cloud プロジェクトでウェブ アプリケーションとして構成）。以下の点を確認してください。
    • 接続する AI クライアント（https://claude.ai/api/mcp/auth_callback、https://chatgpt.com/connector_platform_oauth_redirect、https://antigravity.google/oauth-callback など）に適切な承認済みリダイレクト URI を追加している。
    • [API とサービス] > [OAuth 同意画面] > [データアクセス]（スコープを追加または削除）で、OAuth 同意画面に https://www.googleapis.com/auth/adwords スコープを追加している。
    • OAuth 同意画面の公開ステータスが [テスト]（デフォルト）に設定されている場合は、MCP サーバーに接続する Google アカウントを、[API とサービス] > [OAuth 同意画面] > [オーディエンス]（[テストユーザー] > [+ ユーザーを追加]）でテストユーザーとして追加している。
  • GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET: OAuth クライアント ID に対応する OAuth クライアント シークレット。
  • GOOGLE_ADS_MCP_BASE_URL: MCP サーバーにアクセスできる公開ベース URL（例: https://google-ads-mcp-xyz-uc.a.run.app）。Google Cloud Run は初期デプロイ時にこの URL を生成するため、最初は、この変数を指定せずにデプロイし、デプロイ後にサービスを更新します。
  • FASTMCP_HOST: FastMCP がすべての IP アドレスからの接続を受け入れるようにするには、これを 0.0.0.0 に設定します。

サービスを Google Cloud Run にデプロイします。

gcloud run deploy google-ads-mcp \
  --image us-central1-docker.pkg.dev/YOUR_PROJECT_ID/mcp-servers/google-ads-mcp:latest \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars="GOOGLE_PROJECT_ID=YOUR_PROJECT_ID,GOOGLE_ADS_MCP_OAUTH_CLIENT_ID=YOUR_CLIENT_ID,GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET=YOUR_CLIENT_SECRET,FASTMCP_HOST=0.0.0.0"

Cloud Run でデプロイが完了したら、割り当てられたサービス URL を取得し、GOOGLE_ADS_MCP_BASE_URL 環境変数を使用してサービスを更新します。

gcloud run services update google-ads-mcp \
  --region us-central1 \
  --update-env-vars="GOOGLE_ADS_MCP_BASE_URL=https://your-cloud-run-url.a.run.app"

認証とセキュリティ モデル

--allow-unauthenticated を使用してデプロイすると、Cloud Run のインフラストラクチャ レベルの IAM チェック（roles/run.invoker）が無効になり、外部 AI クライアントが Google Cloud サービス アカウント トークンを必要とせずに接続できるようになります。認証はアプリケーション レイヤに委任されます。

  • GOOGLE_ADS_MCP_OAUTH_CLIENT_ID と GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET が指定されている場合、MCP サーバーはすべての受信リクエストに Google OAuth 2.0 を適用し、認証されていない呼び出し元に HTTP 401 レスポンスを返します。すべてのツール リクエストは、認証された呼び出し元の OAuth ID で厳密に実行されます。
  • --allow-unauthenticated を省略すると、Cloud Run インフラストラクチャ IAM が適用されます。これにより、呼び出し元はリクエストごとに Google Cloud OIDC ID トークンを渡す必要があります。標準の AI クライアント（Claude や ChatGPT など）は、Google Cloud IAM ID トークンではなくエンドユーザー OAuth を使用して認証するため、これらのプラットフォームから直接接続するには、アプリケーション レベルの OAuth を使用する --allow-unauthenticated が必要です。

MCP クライアントを構成する

デプロイ後、Cloud Run の URL を使用して MCP クライアントを構成します。サーバーには OAuth 2.0 認証が必要なため、クライアントは MCP OAuth フローをサポートするか、承認済みの署名なしトークンを提供する必要があります。

  • OAuth 対応クライアント: MCP OAuth 検出をサポートするクライアント（Antigravity など）の場合、エンドポイントに接続すると、Google でログインして https://www.googleapis.com/auth/adwords スコープ（Google Cloud コンソールでは .../auth/adwords として表示）を付与するための認証プロンプトが表示されます。
  • サードパーティの AI プラットフォーム（Claude、ChatGPT）: クライアントのコネクタまたは統合設定で、/mcp パス（例: https://your-cloud-run-url.a.run.app/mcp）を使用して Cloud Run URL を指すカスタム コネクタを追加し、OAuth 2.0 認証（独自の OAuth クライアント ID とクライアント シークレットを使用）を選択します。また、クライアントのコールバック URI が OAuth クライアントの承認済みリダイレクト URI に追加されていることを確認します。（ホスト型エンドポイントのパイロット版の許可リストに登録されている参加者は、ホスト型 MCP の設定ガイドも参照できます）。
  • OAuth をサポートしていないクライアント: HTTP OAuth フローをサポートしていないクライアントは、HTTP 401 Unauthorized レスポンスを受け取ります。これらのツールでは、代わりにローカル stdio 構成を使用します。

OAuth 対応クライアント（~/.gemini/settings.json など）の構成例:

{
  "mcpServers": {
    "google-ads-mcp": {
      "httpUrl": "https://your-cloud-run-url.a.run.app/mcp"
    }
  }
}

コア機能（ツール）

サーバーは、アカウントの検出とパフォーマンス レポート用に設計されたツールを公開します。

  • list_accessible_customers: 認証済みユーザーがアクセスできる Google 広告のお客様 ID とアカウント名のリストを返します。
  • search: GAQL リクエストを実行して、リソースの指標、予算、ステータスを取得します。

  • get_resource_metadata: Google Ads API リソースタイプ（"campaign" など）に関するメタデータを取得します。

    これは、データの構造と、クエリに使用できるフィールドを理解するのに役立ちます。

開始するためのサンプル プロンプト

サーバーにできることを尋ねる:

What can the google-ads-mcp server do?

顧客について尋ねる:

What customers do I have access to?

キャンペーンについて質問する:

How many active campaigns do I have?
How is my campaign performance this week?
Give me a report of the top spending campaigns split by device category over the
last 7 days for account 1234567890

次のステップ