Google Ads MCP サーバー

このリポジトリには、Google Ads API と連携する MCP サーバーのソースコードが含まれています。

ツール

このサーバーは Google Ads API を使用して、LLM や AI エージェントと連携するためのいくつかの ツール と リソース を提供します。

利用可能なツール

• search: Google Ads アカウントに関する情報を取得します。

• get_resource_metadata: Google Ads API リソースタイプ（例: "campaign"）に関するメタデータを取得します。これは、データの構造や、クエリ可能なフィールドを把握するのに役立ちます。

• list_accessible_customers: 呼び出しを認証しているユーザーが直接アクセスできる顧客の ID を返します。

ツールの設定と名前空間

Google Ads MCP サーバーは、tools_config.yaml を使用して、個々のツールやツールカテゴリ（名前空間）を選択的に有効化/無効化したり、それらの名前空間プレフィックスをカスタマイズしたりできます。

すべてのツールが有効化されたデフォルトの tools_config.yaml がパッケージにバンドルされているため、特別な設定をしなくてもサーバーはすぐに使用できます。インストールをカスタマイズする場合、サーバーは以下の順序で設定を解決します。

1. GOOGLE_ADS_MCP_TOOLS_CONFIG 環境変数を介して設定された明示的なパス。

2. カレントワーキングディレクトリにある tools_config.yaml ファイル。

3. パッケージにバンドルされているデフォルトの tools_config.yaml。

明示的に要求された設定ファイル（環境変数経由）が見つからない場合、または解決されたファイルが無効な場合、サーバーはエラーを発生させて起動に失敗します。

設定例:

namespaces:
  # Option 1: Enable category 'customers' with default prefix -> "customers_list_accessible_customers"
  customers: true

  # Option 2: Enable category 'search' with a custom prefix -> "query_search"
  search: "query"

  # Option 3: Fine-grained control over tools in a category
  metadata:
    enabled: true
    prefix: "metadata"
    enabled_tools:
      - get_resource_metadata: true

利用可能なリソース

• discovery-document: Google Ads API のディスカバリドキュメントを取得します。Google Ads API の最新バージョンのディスカバリドキュメントを提供します。これには、リソース、メソッド、スキーマを含む API サーフェスが記述されています。ホスト LLM はこのリソースにアクセスして、Google Ads API の構造を理解し、利用可能な機能を発見する必要があります。

• metrics: Google Ads API でのレポートに利用可能な指標に関する情報を取得します。

• segments: Google Ads API でのレポートに利用可能なセグメントに関する情報を取得します。

• release-notes: Google Ads API の最新バージョンのリリースノートを取得します。

Related MCP server: gads

注意事項

1. MCP サーバーは、接続先のエージェントまたは LLM にデータを公開します。

2. 技術的な問題がある場合は、GitHub 課題トラッカー をご利用ください。

3. 使用状況データの収集を支援するため、API 呼び出しに追加のヘッダーが追加されている場合があります。このデータは製品の改善に使用されます。

セットアップ手順

セットアップには以下の手順が必要です。

1. Python を構成する。

2. デベロッパートークンを構成する。

3. プロジェクトで API を有効にする。

4. 認証情報を構成する。

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

Python の構成

pipx をインストール します。

デベロッパートークンの構成

デベロッパートークンの取得 手順に従います。

デベロッパートークンは、本番アカウントをクエリするには、少なくとも Explorer アクセス権 が必要です。新しいトークンは自動的に Explorer アクセス権にアップグレードされる場合があります。そうでない場合は、API センターから申請できます。詳細については、アクセスレベルに関するドキュメント を参照してください。

「デベロッパートークンはテストアカウントでの使用のみが承認されています」 というエラーが表示される場合、トークンがまだ本番アカウントへのアクセス権を持っていません。必要なアクセスレベルをリクエストする方法については、アクセスレベルに関するドキュメント を参照してください。

プロジェクトで API を有効にする

Google Cloud プロジェクトで以下の API を有効にするには、手順に従って ください。

• Google Ads API

認証情報の構成

オプション 1: FastMCP OAuth プロキシの使用

サーバーは、動的なユーザー認証のために FastMCP の OAuth プロキシ 機能をサポートしています。これは、サーバーをウェブサービスとして実行する場合に便利です。

有効にするには、以下の環境変数を設定します。

• GOOGLE_ADS_MCP_OAUTH_CLIENT_ID: Google Cloud OAuth 2.0 クライアント ID。

• GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET: Google Cloud OAuth 2.0 クライアントシークレット。

• GOOGLE_ADS_MCP_BASE_URL: (オプション) サーバーにアクセス可能なベース URL（デフォルトは http://localhost:8080）。

• GOOGLE_ADS_MCP_JWT_SIGNING_KEY: (オプション) 複数のサーバーインスタンスまたはデプロイメント間で FastMCP JWT トークンに署名するために使用される秘密鍵。

• GOOGLE_ADS_MCP_STORAGE_TYPE: (オプション) OAuth 状態のストレージバックエンド（filetree、redis、firestore、または memory）。

• GOOGLE_ADS_MCP_STORAGE_PATH: (オプション) filetree 永続ストレージのディレクトリパス。

• GOOGLE_ADS_MCP_STORAGE_REDIS_URL: (オプション) redis 永続ストレージの Redis URL。

• GOOGLE_ADS_MCP_STORAGE_FIRESTORE_PROJECT: (オプション) firestore 永続ストレージの Google Cloud プロジェクト。デフォルトは、アプリケーションデフォルト認証情報から推測されるプロジェクトになります。設定すると、GOOGLE_ADS_MCP_STORAGE_TYPE が設定されていなくても firestore バックエンドが選択されます。

• GOOGLE_ADS_MCP_STORAGE_FIRESTORE_DATABASE: (オプション) firestore 永続ストレージの Firestore データベース名。デフォルトは (default) です。

• GOOGLE_ADS_MCP_STORAGE_ENCRYPTION_KEY: (オプション) 保存された OAuth トークンの暗号化キー。

• GOOGLE_ADS_MCP_STORAGE_DISABLE_ENCRYPTION: (オプション) true に設定すると、トークンの暗号化を無効にします。

redis および firestore バックエンドを使用するには、ストレージライブラリをサーバーと一緒にインストールする必要があります: それぞれ pip install py-key-value-aio[redis] および pip install google-ads-mcp[firestore] を実行します。

これが有効になると、MCP クライアントを介して API に認証できるようになります。

これらの変数が設定されると、サーバーは自動的に streamable-http トランスポート（SSE/HTTP）に切り替わり、stdio は使用されなくなります。

サーバーを別のプロセスとして実行し、MCP クライアントが SSE エンドポイント（例: http://localhost:8080/mcp）に接続するように設定する必要があります。

オプション 2: アプリケーションデフォルト認証情報を使用した認証情報の構成

アプリケーションデフォルト認証情報 (ADC) を構成します。認証情報が、Google Ads アカウントまたはプロパティにアクセスできるユーザーのものであることを確認してください。

認証情報には、Google Ads API スコープが含まれている必要があります:

https://www.googleapis.com/auth/adwords

OAuth クライアントの作成方法については、OAuth クライアントの管理 を参照してください。

役立つ可能性のある gcloud コマンドのサンプルをいくつか示します。

• ユーザー認証情報と OAuth デスクトップまたはウェブクライアントを使用して ADC を設定します（クライアント JSON を YOUR_CLIENT_JSON_FILE にダウンロードした後）。

  gcloud auth application-default login \
    --scopes https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform \
    --client-id-file=YOUR_CLIENT_JSON_FILE

• サービスアカウントの権限借用を使用して ADC を設定します。

  gcloud auth application-default login \
    --impersonate-service-account=SERVICE_ACCOUNT_EMAIL \
    --scopes=https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform

gcloud auth application-default コマンドが完了したら、コンソールに出力された次のメッセージ内の PATH_TO_CREDENTIALS_JSON ファイルの場所をコピーします。これは後の手順で必要になります。

Credentials saved to file: [PATH_TO_CREDENTIALS_JSON]

オプション 3: Google Ads API Python クライアントライブラリを使用した認証情報の構成

手順に従って Google Ads API Python クライアントライブラリをセットアップおよび構成します。

すでにこれを行っていて、動作する google-ads.yaml がある場合は、このファイルを再利用できます。

utils.py ファイルで、get_googleads_client() を load_from_storage() メソッドを使用するように変更します。

MCP クライアントの構成

サーバーを MCP クライアントの構成に追加します。以下は、一般的なクライアントの例です。

Antigravity CLI / Antigravity Code Assist

1. Antigravity CLI または Antigravity Code Assist をインストールします。

2. サーバーを構成します。MCP サーバーのセットアップの詳細については、https://antigravity.google/docs/mcp のドキュメントを参照してください。

• オプション 1: FastMCP OAuth プロキシの使用（Streamable HTTP）

  サーバーを別のプロセスとして実行し、MCP クライアントが SSE エンドポイント（例: http://localhost:8080/mcp）に接続するように設定できます。これにより、動的なユーザー認証に FastMCP の OAuth プロキシ 機能を使用することもできます。

  {
    "mcpServers": {
      "google-ads-mcp": {
        "httpUrl":"http://localhost:8080/mcp",
        "env": {
          "GOOGLE_PROJECT_ID": "YOUR_PROJECT_ID",
          "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN"                        
        }
      }
    }
  }

• オプション 2: アプリケーションデフォルト認証情報方式

  PATH_TO_CREDENTIALS_JSON を、前の手順でコピーしたパスに置き換えます。

  また、env オブジェクトに GOOGLE_CLOUD_PROJECT 属性を追加することをお勧めします。次の例の YOUR_PROJECT_ID を、Google Cloud プロジェクトの プロジェクト ID に置き換えます。

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

• オプション 3: Python クライアントライブラリ方式

  {
    "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_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN"
        }
      }
    }
  }

ログイン顧客 ID

マネージャーアカウントを介して顧客アカウントにアクセスする場合は、設定ファイルにマネージャーアカウントの顧客 ID を追加する必要があります。

詳細については、こちら を参照してください。

最終的なファイルは次のようになります:

{
  "mcpServers": {
    "google-ads-mcp": {
      "command": "pipx",
      "args": [
        "run",
        "--spec",
        "git+https://github.com/googleads/google-ads-mcp.git",
        "google-ads-mcp"
      ],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON",
        "GOOGLE_PROJECT_ID": "YOUR_PROJECT_ID",
        "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN",
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "YOUR_MANAGER_CUSTOMER_ID"
      }
    }
  }
}

その他の MCP クライアント（Claude Code、Cursor、VS Code など）

mcpServers ブロックの形式は、すべての MCP クライアントで同じです。上記の構成を、お使いのクライアントの適切な設定ファイルに追加してください（例: Claude Code の場合は ~/.claude/settings.json、Cursor の場合は .cursor/mcp.json、Copilot を使用する VS Code の場合は .vscode/mcp.json）。

Google Cloud Platform へのデプロイ

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

これは、OAuth プロキシ（上記のオプション #1）を介した OAuth クライアント ID とクライアントシークレットのペアによる認証のみをサポートすることに注意してください。

前提条件

1. Google Cloud プロジェクト。

2. gcloud CLI がインストールされ、認証され、アクティブなプロジェクトが設定されていること。

   gcloud config set project YOUR_PROJECT_ID

ステップ 1: Docker イメージのビルドとプッシュ

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

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

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

2. イメージをビルドして送信します:

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

   YOUR_PROJECT_ID を Google Cloud プロジェクト ID に置き換えます。

ステップ 2: Google Cloud Run へのデプロイ

必要な環境変数を必ず設定してください:

• GOOGLE_PROJECT_ID: Google Cloud プロジェクト ID。

• GOOGLE_ADS_DEVELOPER_TOKEN: MCP サーバーが使用するデベロッパートークン（上記参照）。

• GOOGLE_ADS_MCP_OAUTH_CLIENT_ID: MCP サーバーが使用する OAuth クライアント ID。

• GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET: MCP サーバーが使用する OAuth クライアントシークレット。

• GOOGLE_ADS_MCP_BASE_URL: MCP サーバーにアクセス可能なベース URL。初回デプロイ後に Google Cloud Run によって自動的に割り当てられます。デプロイ後に環境変数を更新できます。

• GOOGLE_ADS_MCP_JWT_SIGNING_KEY: （本番環境推奨）Cloud Run インスタンス間で永続化する JWT 署名キー。

• GOOGLE_ADS_MCP_STORAGE_TYPE: （本番環境推奨）インスタンス間で OAuth トークンを永続化するストレージバックエンド。firestore に設定してアプリケーションデフォルト認証情報で Firestore を使用します（VPC コネクタは不要）。redis に設定し、GOOGLE_ADS_MCP_STORAGE_REDIS_URL と併用することもできます。

  firestore を使用するには、3 つの条件を満たす必要があります。1. 追加パッケージをインストールしてイメージをビルドする（Dockerfile を uv pip install --system .[firestore] に変更）。2. プロジェクトに Firestore データベースを作成する（自動プロビジョニングはされません）。3. Cloud Run サービスアカウントに roles/datastore.user ロールを付与する。なお、エントリは自動的に期限切れになりません。ストレージは読み取り時に期限切れエントリをフィルタリングしますが、削除は行わず、expires_at は文字列として書き込まれるため、Firestore の TTL ポリシーでも収集できません。長期運用のデプロイでは、定期的なクリーンアップジョブを計画してください。Redis はエントリを自動的に期限切れにします。

• FASTMCP_HOST: 0.0.0.0 に設定すると、FastMCP がすべての IP アドレスからの接続を受け入れます。

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_DEVELOPER_TOKEN=YOUR_DEVELOPER_TOKEN,GOOGLE_ADS_MCP_OAUTH_CLIENT_ID=YOUR_CLIENT_ID,GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET=YOUR_CLIENT_SECRET,GOOGLE_ADS_MCP_BASE_URL=YOUR_BASE_URL,GOOGLE_ADS_MCP_JWT_SIGNING_KEY=YOUR_JWT_SIGNING_KEY,GOOGLE_ADS_MCP_STORAGE_TYPE=firestore,FASTMCP_HOST=0.0.0.0"

ステップ 3: MCP クライアントを構成する

デプロイ後、https://antigravity.google/docs/mcp のドキュメントを参照して MCP クライアント構成を更新し、Cloud Run URL を使用します。

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

試してみる

MCP クライアントを起動します。利用可能なサーバー一覧に google-ads-mcp が表示されるはずです。

以下のサンプルプロンプトから始めてみてください：

• サーバーでできることを尋ねる：

  what can the 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?

顧客 ID に関する注意

エージェントは、ほとんどのプロンプトで顧客 ID を必要とします。複数の顧客間を行き来する場合は、プロンプトに顧客 ID を含めると簡単です。

How many active campaigns do I have for customer id 1234567890

貢献

貢献大歓迎です！貢献ガイド をご覧ください。