Google 広告 MCP

Google 広告と Claude AI を連携させるツール。自然言語での会話を通じて広告データを分析できます。この統合により、キャンペーン情報、パフォーマンス指標、キーワード分析、広告管理など、すべて Claude との簡単なチャットでアクセスできます。

このツールは広告専門家にとって何に役立つのでしょうか?

1. アカウント管理
   • すべての Google 広告アカウントを 1 か所で確認できます
   • アカウントの詳細と基本的なキャンペーン情報を取得する
2. キャンペーン分析とレポート
   • どのキャンペーンが最も成果を上げているかを知る
   • インプレッション、クリック、コンバージョン、コスト指標を追跡する
   • パフォーマンスの傾向を時間の経過とともに分析する
   • 異なる期間を比較して変化を見つける
   • クロードが作成したチャートとグラフでデータを視覚化します
3. キーワードと広告のパフォーマンス
   • 上位のキーワードと下位のキーワードを特定する
   • 広告コピーの効果を分析する
   • 品質スコアと競合指標を確認する
   • キャンペーンを改善するための実用的な洞察を得る
4. 予算と入札管理
   • キャンペーンの予算と支出を監視する
   • 入札戦略とパフォーマンスを分析する
   • 最適化の機会を特定する
   • 予算配分の推奨事項を取得する

Google 広告 MCP アーキテクチャ フロー

利用可能なツール

この統合を設定したら、Claude に次の操作を依頼できます。

高度なクエリツールの使用

run_gaqlツールは、あらゆるカスタム Google 広告クエリ言語（GAQL）クエリを実行できるため、非常に強力です。以下に、使用できるクエリの例をいくつか示します。

例1: 基本的なキャンペーン指標

例2: 広告グループのパフォーマンス

例3: キーワード分析

利用可能なすべてのツールとその詳細な説明の完全なリストについては、セットアップ後に Claude に「ツールの一覧を表示」するように依頼してください。

はじめに（コーディング経験は必要ありません）

1. Google Ads APIアクセスを設定する

このツールを使用する前に、Claude が Google 広告データにアクセスできるように API 認証情報を作成する必要があります。認証方法は 2 つから選択できます。

オプションA: OAuth 2.0 クライアントID (ユーザー認証)

個々のユーザーまたはデスクトップ アプリケーションに最適:

1. Google Cloud Consoleにアクセスします
2. 新しいプロジェクトを作成するか、既存のプロジェクトを選択してください
3. Google広告APIを有効にする
4. 「認証情報」→「認証情報の作成」→「OAuthクライアントID」に移動します。
5. アプリケーションの種類として「デスクトップアプリケーション」を選択します
6. OAuth クライアント構成ファイル (client_secret.json) をダウンロードします。
7. Google Ads API 開発者トークンを作成する（下記参照）

オプション B: サービス アカウント (サーバー間認証)

自動化システムや複数のアカウントの管理に適しています:

1. Google Cloud Consoleにアクセスします
2. 新しいプロジェクトを作成するか、既存のプロジェクトを選択してください
3. Google広告APIを有効にする
4. 「認証情報」→「認証情報の作成」→「サービスアカウント」に移動します
5. サービス アカウント キー ファイル (JSON) をダウンロードします。
6. サービス アカウントに Google 広告アカウントへのアクセス権を付与します
7. Google Ads API 開発者トークンを作成する（下記参照）

認証トークンの更新

アプリケーションには、堅牢なトークン更新処理が含まれるようになりました。

• OAuth 2.0 トークン: ツールは、可能な場合は期限切れの OAuth トークンを自動的に更新し、更新トークンが無効な場合は再認証を要求します。
• サービス アカウント トークン: サービス アカウント トークンは、ユーザーの介入なしに必要に応じて自動的に生成および更新されます。

認証方法の比較

次の場合は OAuth 2.0 クライアント ID を選択します。

• デスクトップアプリケーションを構築しています
• ユーザーは明示的にアクセスを許可する必要がある
• 1つのアカウントまたはいくつかの個人アカウントを管理している場合
• ユーザーがアクセス権限を制御できるようにしたい

次の場合はサービス アカウントを選択します:

• 自動化システムを構築している
• サーバー間認証が必要です
• 複数のアカウントをプログラムで管理している
• 認証にユーザーによる操作を必要としない
• ユーザーの介入なしにトークンを自動的に更新する必要がある

開発者トークンの取得

1. https://ads.google.comで Google 広告アカウントにログインします。
2. 上部のナビゲーションにある「ツールと設定」（レンチアイコン）をクリックします。
3. 「設定」の下にある「APIセンター」をクリックします。
4. まだ同意していない場合は、利用規約に同意してください。
5. 「トークンを申請」をクリックします
6. APIの使用方法に関する詳細を申請書に記入してください
7. 申請書を提出し、承認を待ちます（通常1～3営業日）

注: 最初は、いくつかの制限があるテスト用の開発者トークンが提供されます。実装をテストした後、これらの制限が解除された本番環境用トークンを申請できます。

ログイン顧客IDの理解

GOOGLE_ADS_LOGIN_CUSTOMER_IDはオプションであり、主に次の場合に使用されます。

• Google 広告クライアント センター（MCC）アカウントをご利用の場合
• そのマネージャーアカウントの下にある複数のクライアントアカウントにアクセスする必要があります

次の場合、ログイン顧客 ID はマネージャーアカウント ID (形式: XXX-XXX-XXXX) にする必要があります。

• MCC アカウントで複数のアカウントにアクセスしています
• クライアント アカウントにアクセスするためにマネージャー アカウントの認証情報を使用したい

次の場合はこの設定をスキップできます。

• 1 つの Google 広告アカウントのみにアクセスしています
• アクセスしたいアカウントの認証情報を直接使用しています

マネージャーアカウント ID を確認するには:

1. Google 広告マネージャーアカウントにログイン
2. 設定アイコン（歯車）をクリックします
3. マネージャーアカウントIDはXXX-XXX-XXXXの形式で表示されます。
4. 資格情報ファイル（JSONファイル）をダウンロードする

**🎬 初心者向けのチュートリアルを YouTube でご覧ください:**近日公開予定

2. 必要なソフトウェアをインストールする

次のツールをコンピューターにインストールする必要があります。

• Python （バージョン3.11以降） - Google広告とClaude間の接続を実行します
• Node.js - MCPインスペクタと特定のMCPコンポーネントを実行するために必要
• Claude Desktop - チャットできるAIアシスタント

続行する前に、Python と Node.js の両方が適切にインストールされ、システム パスで使用可能であることを確認してください。

3. Google広告MCPをダウンロードする

このツールをコンピュータにダウンロードする必要があります。最も簡単な方法は次のとおりです。

1. このページの上部にある緑色の「コード」ボタンをクリックしてください
2. 「ZIPをダウンロード」を選択
3. ダウンロードしたファイルを、簡単に見つけられる場所（ドキュメントフォルダなど）に解凍します。

あるいは、Git に精通している場合は、次の操作を行います。

4. 必要なコンポーネントをインストールする

コンピュータのターミナル (Mac) またはコマンド プロンプト (Windows) を開きます。

1. ファイルを解凍したフォルダに移動します。
   # Example (replace with your actual path): cd ~/Documents/mcp-google-ads-main
2. 仮想環境を作成します (これにより、プロジェクトの依存関係が分離されます)。
   # Using uv (recommended): uv venv .venv # If uv is not installed, install it first: pip install uv # Then create the virtual environment: uv venv .venv # OR using standard Python: python -m venv .venv
   注意: uv をインストールしようとしたときに「pip が見つかりません」というエラーが表示される場合は、以下の「「pip が見つかりません」というエラーが表示される場合」のセクションを参照してください。
3. 仮想環境をアクティブ化します。
   # On Mac/Linux: source .venv/bin/activate # On Windows: .venv\Scripts\activate
4. 必要な依存関係をインストールします。
   # Using uv: uv pip install -r requirements.txt # OR using standard pip: pip install -r requirements.txt # If you encounter any issues with the MCP package, install it separately: pip install mcp
   「pip が見つかりません」というエラーが発生した場合:
   # First ensure pip is installed and updated: python3 -m ensurepip --upgrade python3 -m pip install --upgrade pip # Then try installing the requirements again: python3 -m pip install -r requirements.txt # Or to install uv: python3 -m pip install uv

コマンド プロンプトの先頭に(.venv)が表示される場合、仮想環境がアクティブであり、システムの Python インストールに影響を与えずに依存関係がそこにインストールされることを意味します。

5. 環境設定の設定

Google Ads MCP では、セットアップを容易にするために環境ファイルの構成がサポートされるようになりました。

.env ファイルの使用（推奨）

1. .env.exampleファイルをプロジェクト ディレクトリの.envにコピーします。
   cp .env.example .env
2. 実際の構成値で.envファイルを編集します。
   # Edit the .env file with your favorite text editor # For Mac: nano .env # For Windows: notepad .env
3. .envファイルで次の値を設定します。
   # Authentication Type: "oauth" or "service_account" GOOGLE_ADS_AUTH_TYPE=oauth # Path to your credentials file (OAuth client secret or service account key) GOOGLE_ADS_CREDENTIALS_PATH=/path/to/your/credentials.json # Your Google Ads Developer Token GOOGLE_ADS_DEVELOPER_TOKEN=your_developer_token_here # Optional: Manager Account ID (if applicable) GOOGLE_ADS_LOGIN_CUSTOMER_ID=your_manager_account_id
4. ファイルを保存します。

アプリケーションは起動時に.envファイルからこれらの値を自動的に読み込みます。

直接環境変数を使用する

環境変数は、システム内または Claude または Cursor の構成ファイル内で直接設定することもできます。

クロードデスクトップ向け

カーソル用

6. クロードをGoogle広告に接続する

1. Claude Desktopをまだダウンロードしていない場合はダウンロードしてインストールしてください。
2. Googleサービスアカウントの認証情報がコンピュータのどこかに保存されていることを確認してください
3. コンピュータのターミナル (Mac) またはコマンド プロンプト (Windows) を開き、次のように入力します。

次のテキストを追加します（これにより、Claude に Google 広告への接続方法が伝えられます）。

**重要:**すべてのパスと値をアカウントの実際の情報に置き換えてください。

• 最初のパスは仮想環境内のPython実行ファイルを指す必要があります
• 2番目のパスは、解凍したフォルダ内のgoogle_ads_server.pyファイルを指す必要があります。
• 3番目のパスは、Googleサービスアカウントの認証情報JSONファイルを指す必要があります。
• Google 広告開発者トークンを追加する
• Google 広告マネージャー アカウント ID を追加します（該当する場合）

例:

• マック：
  • Python パス: /Users/ernesto/Documents/mcp-google-ads/.venv/bin/python
  • スクリプトのパス: /Users/ernesto/Documents/mcp-google-ads/google_ads_server.py
• ウィンドウズ:
  • Python パス: C:\\Users\\ernesto\\Documents\\mcp-google-ads\\.venv\\Scripts\\python.exe
  • スクリプトのパス: C:\\Users\\ernesto\\Documents\\mcp-google-ads\\google_ads_server.py

4. ファイルを保存します。
   • Mac: Ctrl+O、Enter、Ctrl+X の順に押して終了します。
   • Windows: ファイル > 保存をクリックし、メモ帳を閉じます。
5. Claudeデスクトップを再起動します
6. Claude が開くと、ツール セクションに利用可能な Google 広告ツールが表示されます。

5a. カーソルに接続（AIコードエディター）

Cursorは、MCPツールで拡張可能なAI搭載コードエディタです。このGoogle Ads MCPツールをCursorと統合することで、コーディング環境内で直接広告データを分析できます。

カーソル統合の設定

1. まだの場合は、 Cursorをダウンロードしてインストールしてください。
2. カーソル MCP 構成ファイルを作成します。**プロジェクト固有の構成の場合:**プロジェクト ディレクトリに.cursor/mcp.jsonファイルを作成します。**グローバル構成の場合 (すべてのプロジェクトで使用可能):**ホーム ディレクトリに~/.cursor/mcp.jsonファイルを作成します。
3. MCP 構成ファイルに次の構成を追加します。
   { "mcpServers": { "googleAdsServer": { "command": "/FULL/PATH/TO/mcp-google-ads-main/.venv/bin/python", "args": ["/FULL/PATH/TO/mcp-google-ads-main/google_ads_server.py"], "env": { "GOOGLE_ADS_CREDENTIALS_PATH": "/FULL/PATH/TO/mcp-google-ads-main/service_account_credentials.json", "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN_HERE", "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "YOUR_MANAGER_ACCOUNT_ID_HERE" } } } }
   重要: Claude Desktop の構成と同様に、すべてのパスと値をアカウントの実際の情報に置き換えます。
4. 新しい構成を適用するには、カーソルを再起動するか、ワークスペースを再ロードします。
5. Google Ads MCP が Cursor の「利用可能なツール」セクションに表示され、必要に応じて Cursor の AI エージェントで使用できるようになります。

カーソルでGoogle Ads MCPを使用する

Cursor で作業している場合、AI エージェントに Google 広告ツールを直接使用するよう指示できます。例:

• 「Google 広告 MCP を使用して、すべてのアカウントをリストし、支出が最も高いアカウントを表示します。」
• 「Google 広告 MCP を使用して、過去 30 日間のキャンペーンのパフォーマンスを分析できますか？」
• 「Google 広告ツールを使用して、GAQL クエリを実行し、コンバージョン率の高いキーワードを見つけます。」

Cursor はツールの使用を承認するように要求し (Yolo モードを有効にしていない場合)、結果をチャット インターフェイスに直接表示します。

カーソル固有の機能

Google Ads MCP を Cursor と組み合わせて使用すると、次のことが可能になります。

1. コードと広告分析を組み合わせる: Cursor に、実際のキャンペーン パフォーマンス データとともにマーケティング関連のコードを分析するよう依頼します。
2. データの視覚化を生成する: 開発環境で直接、広告パフォーマンスのグラフと視覚化をリクエストします。
3. 推奨事項を実装する: 実際の広告データに基づいて、Cursor がコードの改善を提案します。

この統合は、広告のパフォーマンスがコードの決定に直接影響を与えるマーケティング自動化、分析ダッシュボード、または e コマース アプリケーションに取り組んでいる開発者にとって特に価値があります。

6. 広告データの分析を始めましょう!

Google 広告データについて、Claude に質問できるようになりました。Claude はデータを取得するだけでなく、分析、傾向の説明、視覚化も行い、広告のパフォーマンスをより深く理解できるようお手伝いします。

各ツールで使用できる強力なプロンプトをいくつか紹介します。

複数のツールを組み合わせて結果を分析するよう、クロードに依頼することもできます。例えば：

• 「コンバージョン率の高いキーワード上位 20 個を見つけ、品質スコアとインプレッション シェアをチェックして、スケーリングの機会を強調表示するレポートを作成します。」
• 「過去 90 日間のアカウントのパフォーマンス傾向を分析し、最も成長しているキャンペーンを特定し、成長を妨げている予算制限があるかどうかを確認します。」
• 「デスクトップとモバイルの広告パフォーマンスを比較し、その違いをグラフで視覚化し、パフォーマンスのギャップに基づいてモバイル入札調整が必要な特定のキャンペーンを推奨します。」
• 「キーワード リストにない検索語句に最も多くの費用がかかっているキャンペーンを特定し、完全一致キーワードとして追加する必要があるものを提案します。」

Claude は Google 広告ツールを使用してデータを取得し、わかりやすい形式で提示し、必要に応じて視覚化して、結果に基づいて実用的な分析情報を提供します。

データ視覚化機能

Claude はさまざまな方法で Google 広告のデータを視覚化するお手伝いをします。

• トレンドチャート: 時間の経過とともに指標がどのように変化するかを確認します
• 比較グラフ: 異なるキャンペーンや広告グループを比較します
• パフォーマンス分布: デバイスやオーディエンス間での広告のパフォーマンスを把握します
• 相関分析：支出とコンバージョン指標の関係を特定する
• ヒートマップ: 複雑なデータセットを色分けされた表現で視覚化します

データを分析するときに、Claude に「視覚化」または「グラフを作成」するように依頼するだけで、情報をよりよく理解できるように適切な視覚化が生成されます。

トラブルシューティング

Pythonコマンドが見つかりません

macOS では、デフォルトの Python コマンドはpythonではなくpython3であることが多く、Node.js 統合を含む一部のアプリケーションで問題が発生する可能性があります。

Python が見つからないことに関連するエラーが発生した場合は、エイリアスを作成できます。

1. Python エイリアスを作成します (1 回限りの設定):
   # For macOS users: sudo ln -s $(which python3) /usr/local/bin/python # If that doesn't work, try finding your Python installation: sudo ln -s /Library/Frameworks/Python.framework/Versions/3.11/bin/python3 /usr/local/bin/python
2. エイリアスが機能することを確認します。
   python --version

これによりシンボリック リンクが作成され、アプリケーションがpythonを呼び出すときに、実際にはpython3インストールが使用されるようになります。

クロード構成の問題

接続に問題がある場合:

1. 設定内のすべてのファイルパスが正しいことを確認し、フルパスを使用してください。
2. サービス アカウントが Google 広告アカウントにアクセスできることを確認してください
3. 開発者トークンが有効であり、正しく入力されていることを確認してください
4. 変更を加えた後はClaude Desktopを再起動してください。
5. ツールを使用しようとすると、Claude の応答でエラーメッセージが表示されることがあります。
6. サーバーを手動で実行するときに仮想環境がアクティブになっていることを確認してください

Google 広告 API の制限事項

API の割り当てまたは権限に関連する問題が発生した場合:

1. Google Cloud Console で Google Ads API の割り当て制限を確認してください
2. 開発者トークンに適切なアクセスレベルがあることを確認してください
3. サービスアカウントに適切な権限が付与されていることを確認してください

その他の予期しない問題

インストール中または使用中にその他の予期しない問題が発生した場合:

1. 受け取ったエラーメッセージを正確にコピーしてください
2. 以下のサポートについては、Ernesto Cohnen (ernesto@ixigo.com)までお問い合わせください。
   • 何をしようとしていたのか
   • 正確なエラーメッセージ
   • オペレーティングシステム
   • すでに試した手順

また、AI アシスタントに相談することもできます。AI アシスタントは、状況に応じた具体的な解決策を提案することで、技術的な問題の診断と解決に役立ちます。

ほとんどの問題は以前にも他の人が遭遇したことがあり、通常は簡単な解決策があるということを覚えておいてください。

セットアップのテスト

リポジトリには、Claude または Cursor で使用する前に Google Ads API 接続が正しく機能していることを確認できるテスト ファイルが含まれています。

基本機能のテスト

1. 仮想環境がアクティブ化されていることを確認します。
   # On Mac/Linux: source .venv/bin/activate # On Windows: .venv\Scripts\activate
2. テスト ファイルで環境変数を構成するか、環境で設定します。
   • テキストエディタでtest_google_ads_mcp.pyを開きます。
   • if not os.environ.get("GOOGLE_ADS_CREDENTIALS_PATH"):
   • プレースホルダーの値を実際の資格情報に更新するか、環境変数として設定している場合はこのセクションをコメントアウトします。
3. テストを実行します:
   python test_google_ads_mcp.py
4. テストは次のようになります:
   • すべてのGoogle広告アカウントを一覧表示する
   • 最初のアカウントIDを使用してキャンペーンのパフォーマンス取得をテストします
   • テスト広告パフォーマンスデータ
   • 広告クリエイティブを取得する
   • サンプルのGAQLクエリを実行する

認証とトークンの更新のテスト

認証とトークン更新のメカニズムを具体的にテストするには:

1. 仮想環境がアクティブ化され、 .envファイルが構成されていることを確認してください。
2. トークン更新テストを実行します。
   python test_token_refresh.py
3. このテストでは次のことが行われます。
   • 設定された認証タイプ（OAuth またはサービス アカウント）から認証情報が読み込まれることを確認します。
   • 現在のトークンのステータスと有効期限に関する情報を表示します
   • 顧客IDフォーマット機能をテストする
   • OAuthトークンの場合は、トークンを更新して機能していることを確認します。

トークン更新テストは、Claude または Cursor でサーバーを使用する前に、OAuth とサービス アカウントの資格情報の両方が適切に構成されていることを確認するのに役立ちます。

すべてのテストが正常に完了した場合、セットアップは正常に動作しており、Claude または Cursor で使用する準備が整っています。

貢献

バグを発見したり、改善のアイデアをお持ちですか？ご意見をお待ちしております。GitHub で問題を報告するか、プルリクエストを送信するか、Ernesto Cohnen （ernesto@ixigo.com）まで直接お問い合わせください。

ライセンス

このプロジェクトはMITライセンスの下で提供されています。詳細はLICENSEファイルをご覧ください。

ixigoについて

ixigoはインドを代表する旅行アプリで、何百万人もの旅行者が航空券、電車、バス、ホテルの最安値を見つけるお手伝いをしています。詳しくはixigo.comをご覧ください。

ixigoは、航空券、電車、バス、ホテルの最安値を見つけるための製品を開発するテクノロジー企業です。私たちは、旅行をより手頃な価格で、誰もが手軽に楽しめるものにすることに情熱を注ぐ、旅行好きのチームです。