Google Ads MCP Server

🚀 Google Ads MCP Server

FastMCPを活用した、自動OAuth 2.0認証付きGoogle Ads API統合のためのモデルコンテキストプロトコルサーバーです。OAuth 2.0認証、自動トークン更新、GAQLクエリ実行、キーワードリサーチ機能を備え、Google Ads APIをClaude Desktopやその他のMCPクライアントにシームレスに接続します。

🚀 クイックスタート

前提条件

MCPサーバーをセットアップする前に、以下が必要です。

• Python 3.10以上がインストールされていること
• Google Cloud Platformアカウント
• APIアクセスが有効なGoogle Adsアカウント

🔧 ステップ1: Google Cloud Platformのセットアップ

1.1 Google Cloudプロジェクトの作成

1. Google Cloud Consoleにアクセスします。
2. 新しいプロジェクトを作成します。
   • 「プロジェクトを選択」→「新しいプロジェクト」をクリックします。
   • プロジェクト名（例："Google Ads MCP"）を入力します。
   • 「作成」をクリックします。

1.2 Google Ads APIの有効化

1. Google Cloud Consoleで、「APIとサービス」→「ライブラリ」に移動します。
2. 「Google Ads API」を検索します。
3. クリックして「有効にする」を押します。

1.3 OAuth 2.0認証情報の作成

1. 「APIとサービス」→「認証情報」に移動します。
2. 「+ 認証情報を作成」→「OAuth 2.0クライアントID」をクリックします。
3. 同意画面を構成します（初回の場合）。
   • 「同意画面を構成」をクリックします。
   • 「外部」を選択します（Google Workspaceを持っている場合を除く）。
   • 必要なフィールドを入力します。
     • アプリ名："Google Ads MCP"
     • ユーザーサポートメール：あなたのメールアドレス
     • 開発者連絡先：あなたのメールアドレス
   • すべての手順で「保存して続行」をクリックします。
4. OAuthクライアントを作成します。
   • アプリケーションの種類："デスクトップアプリケーション"
   • 名前："Google Ads MCP Client"
   • 「作成」をクリックします。
5. 認証情報をダウンロードします。
   • 「JSONをダウンロード」ボタンをクリックします。
   • ファイルをclient_secret_[long-string].jsonとしてプロジェクトディレクトリに保存します。

🔧 ステップ2: Google Ads APIのセットアップ

2.1 開発者トークンの取得

1. Google Adsにサインインします。
2. 「ツールと設定」（上部ナビゲーションのレンチアイコン）に移動します。
3. 「セットアップ」の下で、「APIセンター」をクリックします。
4. 必要に応じて、サービス利用規約に同意します。
5. 「トークンを申請する」をクリックします。
6. 申請フォームに記入します。
   • ユースケースを説明します（例："キャンペーン分析のためのMCP統合"）。
   • 実装に関する技術的な詳細を提供します。
7. 申請を送信し、承認を待ちます（通常1 - 3営業日）。

注意: 最初は機能が制限されたテストトークンが発行されます。テスト後、本番環境でのアクセスを申請することができます。

2.2 開発者トークンの取得

承認されたら、以下の手順で開発者トークンを取得します。

1. Google AdsのAPIセンターに戻ります。
2. 開発者トークンをコピーします（形式：XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX）。

🔧 ステップ3: インストールとセットアップ

3.1 リポジトリのクローンとインストール

# リポジトリをクローンします
git clone https://github.com/yourusername/google-ads-mcp-server.git
cd google-ads-mcp-server

# 仮想環境を作成します（推奨）
python3 -m venv .venv
source .venv/bin/activate  # Windowsの場合: .venv\Scripts\activate

# 依存関係をインストールします
pip install -r requirements.txt

3.2 環境設定

プロジェクトディレクトリに.envファイルを作成します。

# サンプルファイルをコピーします
cp .env.example .env

.envファイルを編集し、認証情報を入力します。

# 必須: Google Ads API開発者トークン
GOOGLE_ADS_DEVELOPER_TOKEN=your_developer_token_here

# 必須: OAuth認証情報JSONファイルのパス（Google Cloudからダウンロードしたもの）
GOOGLE_ADS_OAUTH_CONFIG_PATH=/full/path/to/your/client_secret_file.json

.envファイルの例:

GOOGLE_ADS_DEVELOPER_TOKEN=ABCDEFG1234567890
GOOGLE_ADS_OAUTH_CONFIG_PATH=/Users/john/google-ads-mcp/client_secret_138737274875-abc123.apps.googleusercontent.com.json

🖥️ ステップ4: Claude Desktopとの統合

4.1 Claudeの設定ファイルを見つける

Claude Desktopの設定ファイルを見つけます。

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

4.2 MCPサーバーの設定を追加する

設定ファイルを編集し、Google Ads MCPサーバーを追加します。

{
  "mcpServers": {
    "google-ads": {
      "command": "/full/path/to/your/project/.venv/bin/python",
      "args": [
        "/full/path/to/your/project/server.py"
      ]
    }
  }
}

実際の例:

{
  "mcpServers": {
    "google-ads": {
      "command": "/Users/marble-dev-01/workspace/google_ads_with_fastmcp/.venv/bin/python",
      "args": [
        "/Users/marble-dev-01/workspace/google_ads_with_fastmcp/server.py"
      ]
    }
  }
}

重要:

• すべてのファイルの場所には絶対パスを使用してください。
• Windowsでは、パスに正斜線/またはダブルバックスラッシュ\\を使用してください。
• your_developer_token_hereを実際の開発者トークンに置き換えてください。

4.3 Claude Desktopを再起動する

Claude Desktopを閉じて再起動し、新しい設定を読み込みます。

🔐 ステップ5: 初回の認証

5.1 OAuthフローを開始する

1. Claude Desktopを開きます。
2. 任意のGoogle Adsコマンドを試します。例えば、

"List all my Google Ads accounts"

5.2 認証を完了する

1. ブラウザが自動的にGoogle OAuthページを開きます。
2. Google Adsアクセス権を持つGoogleアカウントでサインインします。
3. 「許可する」をクリックして権限を付与します。
4. ブラウザに成功画面が表示されます。
5. Claudeに戻ると、コマンドが自動的に完了します！

5.3 セットアップを確認する

認証後、以下のことが確認できるはずです。

• プロジェクトディレクトリにgoogle_ads_token.jsonファイルが作成されていること。
• Claudeの応答にGoogle Adsアカウントが表示されること。

✨ 主な機能

• 🔐 自動OAuth 2.0 - ブラウザでの一度の認証と自動更新
• 🔄 スマートトークン管理 - 期限切れのトークンを自動的に処理
• 📊 GAQLクエリ実行 - 任意のGoogle Adsクエリ言語クエリを実行
• 🏢 アカウント管理 - Google Adsアカウントを一覧表示して管理
• 🔍 キーワードリサーチ - 検索量データを使ってキーワードアイデアを生成
• 🚀 FastMCPフレームワーク - 最新のMCP標準に基づいて構築
• 🖥️ Claude Desktop対応 - Claude Desktopと直接統合
• 🛡️ 安全なローカルストレージ - トークンはローカルに保存され、外部に公開されません

📦 インストール

簡単なワンクリックセットアップ

より簡単なセットアップ体験のために、すぐに使えるインストーラーを提供しています。

👉 インストーラーをダウンロードする - https://gomarble.ai/mcp

💻 使用例

基本的なアカウント操作

"List all my Google Ads accounts"

"Show me the account details and which ones have active campaigns"

キャンペーン分析

"Show me campaign performance for account 1234567890 in the last 30 days"

"Get conversion data for all campaigns in the last week"

"Which campaigns have the highest cost per conversion?"

キーワードリサーチ

"Generate keyword ideas for 'digital marketing' using account 1234567890"

"Find keyword opportunities for 'AI automation' with search volume data"

"Research keywords for the page https://example.com/services"

カスタムGAQLクエリ

"Run this GAQL query for account 1234567890:
SELECT campaign.name, metrics.clicks, metrics.cost_micros 
FROM campaign 
WHERE segments.date DURING LAST_7_DAYS"

"Get keyword performance data:
SELECT ad_group_criterion.keyword.text, metrics.ctr, metrics.average_cpc
FROM keyword_view 
WHERE metrics.impressions > 100"

高度なGAQLの使用例

収益を含むキャンペーンのパフォーマンス

SELECT 
  campaign.id,
  campaign.name, 
  metrics.clicks, 
  metrics.impressions,
  metrics.cost_micros,
  metrics.conversions,
  metrics.conversions_value
FROM campaign 
WHERE segments.date DURING LAST_30_DAYS
ORDER BY metrics.cost_micros DESC

キーワードのパフォーマンス分析

SELECT 
  campaign.name,
  ad_group_criterion.keyword.text, 
  ad_group_criterion.keyword.match_type,
  metrics.ctr,
  metrics.average_cpc,
  metrics.quality_score
FROM keyword_view 
WHERE segments.date DURING LAST_7_DAYS
  AND metrics.impressions > 100
ORDER BY metrics.conversions DESC

デバイス別のパフォーマンスの内訳

SELECT 
  campaign.name,
  segments.device,
  metrics.clicks,
  metrics.cost_micros,
  metrics.conversions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
  AND campaign.status = 'ENABLED'

📚 ドキュメント

利用可能なツール

注意: すべてのツールは自動的に認証を処理するため、トークンパラメータは必要ありません！

プロジェクト構造

google-ads-mcp-server/
├── server.py                           # メインのMCPサーバー
├── oauth/
│   ├── __init__.py                     # パッケージの初期化
│   └── google_auth.py                  # OAuth認証ロジック
├── google_ads_token.json               # 自動生成されるトークンの保存先（gitignored）
├── client_secret_[long-string].json    # あなたのOAuth認証情報（gitignored）
├── .env                                # 環境変数（gitignored）
├── .env.example                        # 環境変数のテンプレート
├── .gitignore                          # Gitの無視ファイル
├── requirements.txt                    # Pythonの依存関係
├── LICENSE                             # MITライセンス
└── README.md                           # このファイル

セキュリティとベストプラクティス

ファイルのセキュリティ

• ✅ 認証情報ファイルはgitignored - バージョン管理にはコミットされません。
• ✅ ローカルトークンストレージ - トークンはgoogle_ads_token.jsonにローカルに保存されます。
• ✅ 環境変数 - 機密データは.envファイルに保存されます。
• ✅ 自動更新 - トークンの露出時間を最小限に抑えます。

推奨されるファイルパーミッション

# 機密ファイルに安全なパーミッションを設定します
chmod 600 .env
chmod 600 google_ads_token.json
chmod 600 client_secret_*.json

本番環境での考慮事項

1. 本番環境では.envファイルの代わりに環境変数を使用します。
2. APIのクォータを尊重するためにレート制限を実装します。
3. Google Cloud ConsoleでAPIの使用状況を監視します。
4. 適切なアクセス制御でトークンを安全に保存します。
5. セキュリティを強化するために定期的にトークンを更新します。

トラブルシューティング

認証に関する問題

設定に関する問題

Claude Desktopに関する問題

APIに関する問題

デバッグモード

トラブルシューティングのために詳細なログを有効にします。

# デバッグ用にserver.pyに追加します
import logging
logging.basicConfig(level=logging.DEBUG)

ヘルプを得る

問題が発生した場合は、以下のことを行ってください。

1. エラーメッセージを注意深く確認します - 通常、正確な問題が示されています。
2. すべてのファイルパスが絶対パスで正しいことを確認します。
3. 環境変数が正しく設定されていることを確認します。
4. Google Cloud ConsoleでAPIのクォータと請求を確認します。
5. 設定を変更した後は、Claude Desktopを再起動します。

高度な設定

HTTPトランスポートモード

Webデプロイメントまたはリモートアクセスのために、サーバーをHTTPモードで起動します。

# サーバーをHTTPモードで起動します
python3 server.py --http

Claude DesktopのHTTP設定:

{
  "mcpServers": {
    "google-ads": {
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

カスタムトークンストレージ

oauth/google_auth.pyでトークンの保存場所を変更します。

# カスタムトークンファイルの場所
def get_token_path():
    return "/custom/secure/path/google_ads_token.json"

マネージャーアカウントの設定

MCCの下で複数のアカウントを管理する場合は、.envファイルに以下を追加します。

# .envファイルに追加します
GOOGLE_ADS_LOGIN_CUSTOMER_ID=123-456-7890

貢献する

我々は貢献を歓迎します！以下は始める方法です。

開発環境のセットアップ

# リポジトリをフォークしてクローンします
git clone https://github.com/yourusername/google-ads-mcp-server.git
cd google-ads-mcp-server

# 開発環境を作成します
python3 -m venv .venv
source .venv/bin/activate

# 依存関係をインストールします
pip install -r requirements.txt

# 開発環境をセットアップします
cp .env.example .env
# .envに開発用の認証情報を追加します

変更を加える

1. 機能ブランチを作成します: git checkout -b feature/amazing-feature
2. 適切なテストを行いながら変更を加えます。
3. さまざまなアカウント設定で十分にテストします。
4. 必要に応じてドキュメントを更新します。
5. 変更をコミットします: git commit -m 'Add amazing feature'
6. ブランチにプッシュします: git push origin feature/amazing-feature
7. 詳細な説明を付けてプルリクエストを開きます。

変更のテスト

# 認証フローをテストします
python3 server.py --test-auth

# API接続をテストします
python3 -c "
from oauth.google_auth import get_oauth_credentials
creds = get_oauth_credentials()
print('✅ Authentication successful!')
"

# Claude Desktopでテストします
# サーバーをClaudeの設定に追加し、さまざまなコマンドをテストします

APIの制限とクォータ

Google Ads APIのクォータ

• 基本アクセス: 1日あたり15,000オペレーション
• 標準アクセス: 1日あたり40,000オペレーション
• リクエストレート: 開発者トークンあたり1分あたり1,600リクエスト

API使用のベストプラクティス

1. 可能な場合は結果をキャッシュして、API呼び出しを減らします。
2. 日付範囲を使用してデータ量を制限します。
3. サポートされている場合はリクエストをバッチ処理します。
4. Google Cloud Consoleで使用状況を監視します。
5. レート制限エラーに対してリトライロジックを実装します。

クォータ管理

# Google Cloud Consoleで使用状況を監視します
# APIとサービス → クォータに移動します
# "Google Ads API"を検索して現在の使用状況を確認します

🔧 技術詳細

プロジェクト構造

google-ads-mcp-server/
├── server.py                           # メインのMCPサーバー
├── oauth/
│   ├── __init__.py                     # パッケージの初期化
│   └── google_auth.py                  # OAuth認証ロジック
├── google_ads_token.json               # 自動生成されるトークンの保存先（gitignored）
├── client_secret_[long-string].json    # あなたのOAuth認証情報（gitignored）
├── .env                                # 環境変数（gitignored）
├── .env.example                        # 環境変数のテンプレート
├── .gitignore                          # Gitの無視ファイル
├── requirements.txt                    # Pythonの依存関係
├── LICENSE                             # MITライセンス
└── README.md                           # このファイル

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細については、LICENSEファイルを参照してください。

MITライセンス

Copyright (c) 2025 Google Ads MCP Server Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

📈 ロードマップ

今後の機能

• 🔄 競合他社分析を含む強化されたキーワードリサーチ
• 📊 チャートとグラフによる組み込みデータ可視化
• 🤖 AIによる最適化提案
• 📝 キャンペーン作成と管理ツール
• 🔍 高度なレポート機能
• 🌐 多言語サポート

Made with ❤️ for the MCP community

Google Adsのデータを直接AIアシスタントに接続し、自然言語での会話を通じて強力な広告洞察を引き出しましょう。

コミュニティに参加して、ヘルプとアップデートを受け取りましょう

👉 Slackコミュニティ - AI in Ads

Facebook広告MCPサーバーも試してみましょう

👉 Facebook Ads MCP - Facebook Ads MCP