Google Ads Mcp Server

Google Ads MCP サーバー 🚀

Google Ads API 統合のための FastMCP 搭載 Model Context Protocol サーバー。OAuth 2.0 認証を自動化します

シームレスな OAuth 2.0 認証、自動トークン更新、GAQL クエリ、キーワードリサーチ機能により、Google Ads API を Claude Desktop やその他の MCP クライアントに直接接続します。

お使いのブラウザーは video タグをサポートしていません。

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

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

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

サポートと最新情報のためのコミュニティに参加しましょう

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

Facebook Ads MCP サーバーもお試しください

👉 Facebook Ads MCP - Facebook Ads MCP

✨ 機能

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

📋 利用可能なツール

ツール	説明	パラメーター	使用例
list_accounts	アクセス可能なすべての Google Ads アカウントを一覧表示	なし	「すべての Google Ads アカウントを一覧表示して」
run_gaql	カスタムフォーマットで GAQL クエリを実行	customer_id、query、manager_id（任意）	「アカウント 1234567890 のキャンペーンパフォーマンスを見せて」
run_keyword_planner	指標付きのキーワードアイデアを生成	customer_id、keywords、manager_id、page_url、日付範囲オプション	「『デジタルマーケティング』のキーワードアイデアを生成して」

注意: すべてのツールは認証を自動的に処理します - トークンパラメーターは不要です！

🚀 クイックスタート

前提条件

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 とサービス」→「ライブラリ」に移動します
   • 「Google Ads API」を検索します
   • それをクリックし、「有効にする」を押します

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 クローンとインストール

# Clone the repository
git clone https://github.com/yourusername/google-ads-mcp-server.git
cd google-ads-mcp-server

# Create virtual environment (recommended)
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

3.2 環境設定

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

# Copy the example file
cp .env.example .env

.env を認証情報で編集します:

# Required: Google Ads API Developer Token
GOOGLE_ADS_DEVELOPER_TOKEN=your_developer_token_here

# Required: Path to OAuth credentials JSON file (downloaded from 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 アカウント（Google Ads へのアクセス権を持つもの）でサインインします
3. 「許可」をクリックして権限を付与します
4. ブラウザに成功ページが表示されます
5. Claude に戻ります - コマンドが自動的に完了します！

5.3 セットアップの確認

認証後、次のことが確認できるはずです:

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

📖 使用例

基本的なアカウント操作

"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                           # Main MCP server
├── oauth/
│   ├── __init__.py                     # Package initialization
│   └── google_auth.py                  # OAuth authentication logic
├── google_ads_token.json               # Auto-generated token storage (gitignored)
├── client_secret_[long-string].json    # Your OAuth credentials (gitignored)
├── .env                                # Environment variables (gitignored)
├── .env.example                        # Environment template
├── .gitignore                          # Git ignore file
├── requirements.txt                    # Python dependencies
├── LICENSE                             # MIT License
└── README.md                           # This file

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

ファイルのセキュリティ

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

推奨されるファイル権限

# Set secure permissions for sensitive files
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. セキュリティ強化のために定期的なトークンローテーションを行います

🛠️ トラブルシューティング

認証の問題

問題	症状	解決策
トークンが見つからない	「Starting OAuth flow」というメッセージ	✅ 初回セットアップでは正常です - ブラウザでの認証を完了してください
トークンの更新に失敗	「Refreshing token failed」エラー	✅ google_ads_token.json を削除して再認証してください
OAuth フローの失敗	ブラウザエラーまたは応答なし	認証情報ファイルのパスとインターネット接続を確認してください
アクセス許可が拒否された	ブラウザに「Access denied」と表示される	Google アカウントに Google Ads へのアクセス権があることを確認してください

設定の問題

問題	症状	解決策
環境変数が不足している	「Environment variable not set」	.env ファイルと Claude 設定の env セクションを確認してください
ファイルが見つからない	「FileNotFoundError」	設定内の絶対パスを確認してください
モジュールのインポートエラー	「ModuleNotFoundError」	pip install -r requirements.txt を実行してください
Python パスの問題	「Command not found」	Python 実行ファイルへの絶対パスを使用してください

Claude Desktop の問題

問題	症状	解決策
サーバーに接続できない	Google Ads ツールが利用できない	Claude Desktop を再起動し、設定ファイルの構文を確認してください
無効な JSON 設定	Claude の起動エラー	設定ファイルの JSON 構文を検証してください
権限エラー	起動時の「Permission denied」	ファイルの権限とパスを確認してください

API の問題

問題	症状	解決策
無効な顧客 ID	「Customer not found」	ハイフンなしの 10 桁形式を使用してください: 1234567890
API クォータ超過	「Quota exceeded」エラー	クォータのリセットを待つか、増加をリクエストしてください
無効な開発者トークン	「Authentication failed」	Google Ads API Center でトークンを確認してください
GAQL 構文エラー	「Invalid query」	GAQL の構文とフィールド名を確認してください

デバッグモード

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

# Add to server.py for debugging
import logging
logging.basicConfig(level=logging.DEBUG)

ヘルプの入手

問題が発生した場合:

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

🚀 高度な設定

HTTP トランスポートモード

Web デプロイまたはリモートアクセスの場合:

# Start server in HTTP mode
python3 server.py --http

HTTP 用の Claude Desktop 設定:

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

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

oauth/google_auth.py 内のトークンストレージの場所を変更します:

# Custom token file location
def get_token_path():
    return "/custom/secure/path/google_ads_token.json"

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

MCC 配下で複数のアカウントを管理する場合:

# Add to .env file
GOOGLE_ADS_LOGIN_CUSTOMER_ID=123-456-7890

🤝 コントリビューション

コントリビューションを歓迎します！始め方は次のとおりです:

開発環境のセットアップ

# Fork and clone the repository
git clone https://github.com/yourusername/google-ads-mcp-server.git
cd google-ads-mcp-server

# Create development environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Set up development environment
cp .env.example .env
# Add your development credentials to .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. 詳細な説明を添えてプルリクエストを開く

変更のテスト

# Test authentication flow
python3 server.py --test-auth

# Test API connectivity
python3 -c "
from oauth.google_auth import get_oauth_credentials
creds = get_oauth_credentials()
print('✅ Authentication successful!')
"

# Test with Claude Desktop
# Add your server to Claude config and test various commands

📊 API の制限とクォータ

Google Ads API のクォータ

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

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

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

クォータ管理

# Monitor usage in Google Cloud Console
# Go to APIs & Services → Quotas
# Search for "Google Ads API" to see current usage

📄 ライセンス

このプロジェクトは 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 を活用した最適化の提案
• 📝 キャンペーン作成および管理ツール
• 🔍 高度なレポート機能
• 🌐 多言語サポート

---

MCP コミュニティのために ❤️ を込めて作りました

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